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Glossary~1 


Ind-1 


PREFACE 


This manual describes the Perkin-Elmer Common Assembly Language 
(CAL) Macro/32 Processor, Program Number 03-339, and its use in 
defining macro instructions for frequently used sequences of 
assembler code, for creating a macro library, and for expanding 
macro instructions during the assembly process. 


Chapter 1 introduces the CAL Macro/32 Processor and explains 
processor requirements, processor components, and summarizes 
macro processor features. Chapter 2 details macro instructions, 
Macro definitions, special symbols, macro definition contents, 
and model statements. Chapter 3 explains how to write a macro 
instruction, Macro instruction operands, and inner and outer 
macro instructions. Chanter 4 is an in-depth discussion of the 
conditional expansion of macro definitions. Additional CAL 
Macro/32 features are presented in Chapter 5, and the operation 
of the macro processor is discussed in Chapter 6. Chapter 7 
details each macro library utility command. 


Appendix A is a command summary of the CAL Macro/32 Processor 
utility commands. Appendix B contains the macro instructions and 
Statements. Appendix C contains examples of macro expansion, and 
Appendix D presents the CAL Macro/32 Processor error messageSe 
The CAL Macro/32 Processor now supports batch global set variable 
symbols, passes MLIBS and MCOPY from start options to all 
programs in the batch, and generates an END statement without 
terminating macro expansion if it is within the scope of an ASIS 
statement. 


This manual replaces S$29-408 and discusses revision RO2.1 of the 
CAL Macro/32 Processor and the Macro Processor Utility. This 
revision applies to the 0OS/32 RO6 software release and higher. 


These manuals provide information related to the use of the 
various programs in the CAL Macro/32 Processor: 


PUBLICATION 
MANUAL TITLE NUMBER 
0OS/32 System Macro Library Reference Manual 48-006 
OS/32 Library Loader Reference Manual 48-020 
0S/32 Operator Reference Manual 48-030 
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Common Assembly Language/32 (CAL/32) 
Reference Manual | 48-050 


32-Bit Systems User Documentation Summary 50-093 


For further information on the contents of all Perkin-Elmer 
32-bit manuals, see the 32-bit Systems User Documentation 
Summary. 
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CHAPTER 1 
CAL MACRO/32 PROCESSOR 


1.1 INTRODUCTION 

The Perkin-Elmer CAL Macro/32 Processor provides the user of CAL 
with a tool to standardize and efficiently generate programs. 
This ability is provided by the system macro library and any user 
designated special purpose libraries. Frequently used assembler 
code sequences are defined once and then appended to a macro 
library by a macro definition. By inserting a single source 
statement that the processor recognizes and expands, these code 
sequences are made available to all system users. 

1.2 CAL MACRO/32 PROCESSOR REQUIREMENTS 


The CAL Macro Processor requires: 


e Any Perkin-Elmer 32-bit rfrocessor 


@ Main memory of 26kb above that memory required for the 
operating system and macro system table 


® C0S/32 


e Source input, source output, and listing devices 


1-2-1 Configuration Option 

The CAL Macro Processor can use any Perkin-Elmer peripheral 
device that the operating system supports, if the program can run 
on the device and is capable of ASCII data transfer. 


1e2-2 Relationship to Other Products 


The CAL Macro Processor produces an expanded source stream that 
must be assembled with CAL (03-066R05 or higher). 
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1-3 CAL MACRO/32 PROCESSOR COMPONENTS 


The CAL Macro Processor package consists of: 


CAL Macro Library Utility Object, 03-340 
CAL Macro Processor Object, 03-339M 
OS/32 System Macro Library, 07-217 


CAL Macro/32 Processor and Macro Library Utility Reference 
Manual ; 


0S/32 System Macro Library Reference Manual 


1-4 SUMMARY OF CAL MACRO/32 PROCESSOR FEATURES 


The CAL Macro Processor offers these features: 


Positional, keyword, Or mixed mode macro prototype statements 
Nested macro instructions 


Conditional macro exfbansion independent of assembler 
conditional statements 


Symbolic parameters that can vary the operation codes expanded 
to the assembler source etream 


A macro call (MCCALL) instruction that allows the most used 
macro definitions to be called into memory at the start of 
macro processor execution, thus decreasing the number of 
library accesses necessary during the processor pass 


A macro trace (MTRAC) facility that allows the user to test a 
Macro instruction expansion without going through the full 
assembly process 


User designation of macro libraries and the order in which 
they should be searched 


A system macro library of standard macro definitions 


A macro library utility program that builds and maintains the 
Macro libraries. Special features allow adding and deleting 
macro definitions, generating a library table of contents, and 
copying macro definitions from existing macro libraries. 
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The power of the macro language is shown in its ability to: 


@e pass parameters to a macro and concatenate the parameter to 
characters in the macro to form new labels, operations, and 
Farameters that allow the user to write macros for many 
"housekeeping" functions that normally would have to be 
performed in a program; and 


e define symbols local to the macro, assign values to _ those 


symbols, and make complex tests on the values of those symbols 
or on parameters passed to the macro. 
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CHAPTER 2 
PREPARATION OF A MACRO DEFINITION 


2e1 INTRODUCTION 

The following sections discuss what a macro instruction is, its 
interaction with the Common Assembly Language (CAL) Macro/32 
Processor, and the preparation of a macro definition. 

2-2 MACRO INSTRUCTIONS 

A macro instruction is a single instruction that expands to a 
series of instructions. A macro instruction is written like an 
assembler instruction; but the output, when processed by the CAL 


Macro Processor Program, is in assembly language. 


The rules for the syntax of a macro instruction are: 


e Columns 1 through 8 contain a symbal or blanks. 
e Columns 10 through 17 contain the macro name. 


e At least one blank space must be on either side of the macro 
name. 


e One blank space separates the label field from the macro call, 
and one blank space separates the macro call from _ the 
parameter. 


e A comma must be specified to show omitted positional 
Parameters. 


e Keyword parameters can be written in any order. 

e Subparameters are enclesed in parentheses and can only be 
positional. 

The output of a macro instruction can be: 

@ machine instructions, 

e another macro instruction, 

e assembler instructions, or 


@® a ocombination of machine and assembler instructions. 
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This output process is the macro expansion. The assembler 
processes the output as if the user had written the expanded 
coding in detail. Macros are a valuable coding tool--they enable 
the user to avoid writing many system required details; thus, 
reducing the chance of errors. The user can use the standard 
Perkin-Elmer macros in the system macro library or write his own 
Macros and store them ina user library. 


2-3 MACRO DEFINITIONS 


A macro definition is a series of user-written instructions in 
the macro language. The definition of a macro can include: 


@ machine instructions such as ADD, SUBTRACT, LOAD, or STORE; 
@e assembler instructions such as DS or DC; 
@® macro language instructions such as AIF, AGO, or SETA; or 


@e another macro instruction, which would be an inner macro. 


The macro definition allows the user to assign a macro 
instruction to be used in the operation field of the macro 
instruction syntax. A macro instruction retrieves and processes 
the definition. 


If the macro definition has no errors, processing the macro 
definition call results in generating zero or more assembler 
source statements that become part of the assembler source stream 
and appear in the assembler source stream immediately after the 
Macro instruction. The assembler source statements the processor 
produces are referred to as generated (or expanded) statements. 
The macro expansion process involves the processor analyzing the 
Macro instruction and definition, and generating assembler source 
statements. 


20301 Macro Definition Fields 


A macro definition minimally consists of these fields: 


e The name field begins in column 1. If the name field is 
omitted, column 1 must be blank. 


e The operation field must start in column 10. If concatenation 
is not used, the maximum length of the operation field is 
eight characterse If concatenation is used, the operation 
field can exceed . eight characters. Whether Or not 
concatenation is used, the operation field of a generated 
statement must contain from one to five characters. If the 
generated statement is a macro instruction, the operation 
field can contain a maximum of eight characters. 
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e The operand field follows the operation field, separated by at 
least one blank. The operand field can extend as far as 
column 71 ona Single statement Line and can be continued in 
another line by inserting a nonblank character in column 72 
(the continuation field). A generated CAL statement, however, 
cannot contain an operand field extending beyond a single 
statement line. Continuation can be invoked only from the 
operand field. 


e The comment field follows the operand field, separated by at 
least one blank column. This field contains user comments. 


e The continuation field follows the comments field. In a 
keyword or mixed mode prototype statement, each operand can 
appear on a Single line if it is followed by a comma, and a 
nonblank character appears in the continuation field. 


e The identification/sequence field accupies columns 73 through 
80. The user has the option of identifying and maintaining 
the sequence of the source field. 


Figure 2-1 illustrates the fields used for writing macro 
instructions. 


2618 


IDENTIFICATION 
OPERAND “ COMMENTS SEQUENCE 


* THE OPERAND FIELD CAN EXTEND AS FAR AS COLUMN 71 ON A SINGLE STATEMENT LINE. 
** CONTINUATION FIELD 


Figure 2-1 Fields Used for Writing Macro Instructions 
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2-4 SPECIAL SYMBOLS 
The following symbols have special meanings to the CAL Macro 
Processor: 

SYMBOL MEANING 


vA A percent sign identifies variable symbols 
used within the macro definition. 


A colon is a concatenation symbol; or, if it 
is found in column 1 followed by an asterisk 
in column 2, it identifies comments internal 
to the macro definition. 


& An ampersand identifies sequence symbols used 
in a macro definition. 


For each of these symbols except the ampersand (&), if two 
Symbols are input, only one symbol is output. 


2-421 Variable Symbols 


Macro language allows the user to define variable symbols, assign 
values to variable symbols, and test the values of variable 
symbols. The macro processor uses variable symbols as symbolic 
parameters, system symbols, and set symbols. It uses variable 
symbols like the assembler uses symbolic names. Variable symbols 
can be used in arithmetic expressions, binary or Boolean 
expressions, or character expressions. These guidelines apply to 
variable symbols: 


e The first character ina variable symbol must be a percent 
sign (%). 

e The second character in a variable symbol must be a letter. 

e The remaining zero to six characters can be letters or digits. 

e Characters 2, 3, and 4 must not form the word SYS because 
these letters define system variables. 


Valid examples of variable symbols are: 


AREG AAREA ALOC ”LOC 1 ”zA123 
AINCDEX ALABLE ANAME *LIST 
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264.121 Local, Global, and Batch Global Variable Symbols 


Variable symbols can be local, global, or batch global. 
Parameters are always local. If a variable symbol is batch 
global, the value assigned to it in one program can be used in 
another program in the same batch. The macro processor 
initializes batch global variables when they are encountered 
first in the batch. The macro processor does not initialize 
subsequent definitions of batch global variables in that batch. 
If a variable symbol is global, the value assigned in one macro 


can then be used in another macro. The macro processor 
initializes global variables when they are first encountered in 
a program. The processor does not reinitialize subsequent 


definitions of global variables in that program. Local variables 
are initialized each time they are defined. They must be defined 
before they can be used, and their values do not carry from one 
macro definition to another. 


New values can be reassigned to local, global, and batch global 
variable symbols by these macro language instructions: 


INSTRUCTION MEANING 
SETA Assign arithmetic value. 
SETB Assign binary or Boolean value of 0 (false) or 
1 (true). 
SETC Assign character value. 


Section 4.3 details these SET variable symbol statements. 


2-4.1-2 Defining Variable Symbols 


A variable symbol is defined explicitly in the body of the macro 
definition. It is assigned a value, which can be changed, in the 
macro body. These Macro language statements define and 
initialize variable symbols: 


STATEMENT MEANING 

LCLA Local arithmetic; initial value 0 

LCLB Local binary or Boolean; initial value 0 
LCLC Local character; initial value null ‘' 
GBLA Global arithmetic; initial value 0 

GBLB Global binary or Boolean; initial value 0 
GBLC Global character; initial value null ‘' 
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STATEMENT MEANING 


BGBLA Batch global arithmetic; initial value 0 

BGBLB - - Value batch global binary or Boolean; initi 
value 0 

BGBLC Batch global character; initial valve null 


Sections 4.2.1 and 4.2.2 detail these 

local, global, and batch glcockal 

SET variable symbol declaration statements. 

2-4.2 Concatenation Symbols 

Variable symbols can be cecncatenated on the left or right with 
any other characters to form a new string. This concatenation 
can occur in the label, cperation, Or operand fields. The 
ability to concatenate is advantageous because the macro 
expansion can be different in different calls. 

When concatenating to the right of a variable symbol, a colon 
indicates the concatenation. The colon is optional except when 
the next character is: 

e alphanumeric, 


@® aocolon, or 


e a left parenthesis [ G Vs 


Valid examples of concatenation symbols are: 


ABC2SYM ASYM:3 (R4) ASYMsABC 


2-4.3 Sequence Symbols 

Sequence symbols are used to branch within a macro. They can 

appear in a statement name field to vary the statement processing 

sequence. These guidelines apply to sequence symbols: 

e The first character must be an ampersand (&). 

e The second character must be a letter. 

e The remaining zero to six characters can be letters or digits. 

@e Sequence symbols can appear in the name field of any statement 
not containing a symbol except a prototype statement, an ACTR, 


BGBLA, BGBLB, BGBLC, GBLA, GBLB, GBLC, LCLA, LCLB, LCLC, or 
MACRO instruction. 
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Valid examples of sequence symbols are: 


EDONE &END &MORE &A123 
ENEXT & AGAIN &LOOKUP 


2-5 MACRO DEFINITION CONTENTS 


The contents of a macro definition are written in this sequence: 


1¢ A macro header, indicated by the word MACRO, is written in 
column 10. 


2e A prototype statement, the method by which the macro is 
called, is written next. If a macro call is to have a label 


Or parameters, they must be defined in the prototype 
statement. 
36 The macro definition body can contain optional model 


statements, which are assembler instructions. The macro body 
can also contain any macro instructions. In general, macro 
instructions declare variables and assign values to 
variables, contain unconditional branches, and conditional 
branches. Examples are: 


- Local variable (LCLx), global variable (GBLx), and batch 
global variable (BGBLx) declaration statements 


~ MEXIT, MNOTE, SETx, AIF, and AGO instructions 


4G. Amacro definition is terminated with the macro trailer, 
MEND. 


This example illustrates a macro definition: 


NAME OPERATION OPERAND TYPE 
MACRO 1 
%NAME MOVE ”AFROM,%TO 2 
%NAME ST 1,HOLD 3 
L 1,%FROM 3 
ST 1,%T0 3 
L 1,HOLD 3 
MEND 4 


LEGEND FOR TYPE COLUMN 


macro header 
macro prototype 
model statement 
macro trailer 


eWwWN- 
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Macro definitions eae placed in the source stream or in 
special libraries. If they are defined in the source program, 
they must be written before any calls to the macro. If a macro 
is defined in a library, the appropriate logical unit must be 
assigned to define the macro library and a given MLIBS statement. 
See Section 5.1.5.6 


2-5-1 Macro Header and Trailer Statements 


The macro header, which indicates the beginning of a macro 
definition, must be the first statement. The MACRO statement is 
written in this format: 


NAME OPERATION OPERAND COLUMN 72 


optional MACRO version nmumber and blank 
date, or any other 
optional description 


The macro trailer, which indicates the end of a macro definition, 
Must be the last statement in the definition. The MEND statement 
is written in this format: 


NAME OPERATION CPERAND COLUMN 72 
a sequence MEND | blank blank 
symbol or 
blank 


2-5-2 Macro Instruction Prototype Statements 


The macro is called by the macro prototype statement. If the 
macro call is to Have any labels or parameters, they must be 
defined in the protdtype statement. The parameters can be 


positional, keyword, gr mixed mode. 


The prototype statement specifies the mnemonic operation code and 
general format to be used when writing any macro instructions 
referring to this definition. This statement must immediately 
follow the macro header, MACRO. 


2e5e2-1 Positional Macro Instruction Prototype Statements 


A positional macro ‘instruction prototype statement contains 
positional parameters that must be specified in the defined 
order. The aaa pretctype statement is written in this 
format: 
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NAME OPERATION OPERAND 


a Symbolic a 1- to 8- Zero or more 
parameter character mnemonic symbolic parameters 
or biank operation code separated by commas 


The symbolic parameters used in the macro definition represent 
the name field and orerands of the corresponding macro 
instruction. A symbolic parameter is a variable symbol 
consisting of a percent sign followed by from one to seven 
letters or numbers, the first of which must be a letter. 


A macro instruction must use the mnemonic operation code to refer 
to this macro definition. If two macro definitions use the same 
mnemonic operation code, the first definition the macro processor 
encounters is expanded; the second definition is flagged with an 
error message. If a macro definition uses the same mnemonic 
Operation code asa valid assembler or machine instruction, the 
macro processor treats it as a macro instruction. To override 
the macro instruction and obtain the machine instruction, use the 
ASIS statement. See Section 5.11. 


A positional prototype statement can be continued if the operand 
field extends beyond column 71. Section 3.3.1 explains 
continuation rules. This example illustrates a positional macro 
instruction prototype statement: 


NAME OPERATION OPERAND 


*ANAME MOVE AF ROM, %TO 


2e5e2e2 Keyword Macro Instruction Prototype Statements 


In a keyword prototype statement, any symbolic parameter in the 
operand field of the fgretotype statement can have a standard 
value assigned to it. If a symbolic parameter is omitted when 
the macro instruction is written, the macro processor substitutes 
the standard value. This substitution allows the user to omit 
symbolic parameters whose values are not to be changed when 
writing a keyword prototype statement. The operands in a macro 
instruction that reference a macro definition with a keyword 
prototype statement can be written in any sequence. A keyword 
prototype statement can be continued to the next statement. 
Section 3.3.1 explains the rules for continuation. The keyword 
prototype statement is written in this format: 
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NAME ' OPERATION OPERAND 


any symbolic a ‘1- to 8- one or more operands 
parameter or character separated by commas 
blank mnemonic and consisting of a 
operation symbolic parameter, 

code immediately followed 
by an equal Sign 


followed (optionally) 
by a standard value. 


With the exception of variable symbols, whatever can be used as 
an operand in a macro instruction can be used as a standard 
value. Following is an example of a macro uSing a_ keyword 
prototype macro statements: 


NAME OPERATION OPERAND TYPE 
MACRO 1 
%SYM MOVE %FROM=,%TC=,%HOLD=HOLD1,%R=1 2 
SYM ST | %R,%HOLD 3 
L | %R ,pAFROM 3 
ST | %R,%TO 3 
L | %R,%HOLD 3 
MEND r 
A MOVE FROM=SOURCE,R=5, TO=DEST 5 
A ST | 5,HOLD1 6 
L , 5,SOURCE 6 
ST ! 5,DEST 6 
L | 5,HOLD1 6 


LEGEND FOR TYPE COLUMN 


macro header 

macro prototype 
model statement 
macro trailer, 
macro instruction 
generated statement 


AM fWwhN a 


2050223 Mixed Mode Macro Instruction Prototype Statements 


Macro instructions can be defined with positional and keyword 
parameters. When a macro is called, the positional parameter 
must be specified first in the defined order. The positional 
parameters are followed by keyword parameters in any order. 
Omitted positional parameters must be indicated by a comma, 
except when all trailing positional parameters are omitted. The 
mixed mode prototype statement is written in this format: 
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NAME OPERATICN 
any symbolic a t- to 8- 
Parameter or character 
biank mnemonic 

code 


OPERAND 


one or more positional 
parameters followed by 
one or more keyword 
parameters (see Section 
2050202) 


The following is an example of a mixed mode prototype statement: 


NAME 


ASYM 


The following is a macro instruction with the 


parameter omitted. Lt. i 


EX4 ABC,,3,K1=A 


The following is a macro instruction with the 
positional parameters omitted. 


EX4 ABC,K2=BETA 


A mixed mode instruction can be continued to the next 


OPERATION 


EX4 


s coded as: 


LPHA 


OPERAND 


%4P1,%P2,%P3,24K1=,2%K 2= 


It is coded as: 


second positional 
second and third 
statemente 


Section 3.3.1 explains continuation rules. 


2-6 MODEL STATEMENTS 


The CAL Macro Processor expands 


from model statements. 
within a given macro 
four fields: 

e Name 

e Operation 


e Operand 


e Comments 


the 


desired source statements 


Any number of model statements can appear 


definition. 


Model statements consist of 


These fields correspond to the same fields in the expanded source 


statemente 


The CAL Macro Processor does not check 


the expanded 


source statements for the ccrrect assembler syntax. 
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2-6-1 Name Field 

The name field, which begins in column 1, can be blank or it can 
contain a: 

@e name, 

@ variable symbol, or 

® sequence symbol. 

It can also contain a name concatenated with a variable symbol or 
a variable symbol concatenated with one or more other variable 
symbols. 

2-6.2 Operation Field 

At least one blank character separates the operation field from 
the name field. It can contain: 

@e@ a machine instruction, 

@® an assembler instruction, 

@® a macro instruction, or 

@ a variable symbol. 

It can also contain a name concatenated with a variable symbol or 
a variable symbol concatenated with one or more other variable 
Symbols. 


Variable symbols cannot be used to generate more than one field 
at a time, macro protdtypes, or these instructions: 


ACTR END MCALL MTRAC 
AGC GBLA MCOPY NDEFS 
AIF GBLB MDEFS NOLIB 
ANOP GBLC MEND NTRAC 
ASIS LCLA MEXIT SETA 
BGBLA LCLB MLIBS SETB 
BGBLB LCLC MNOTE SETC 


BGBLC MACRO MPAUS 


222 48-057 FOO ROO 


2-6.3 Operand Field 


At least one blank character separates the operand field from the 
operation field. It can contain; 


@e names, 
@e variable symbols, or 


@ constants. 


It can also contain names concatenated with other symbols or 
variable symbols concatenated with one or more other variable 
symbols. 


2e6-4 Comments Field 


At least one blank character separates the comments field from 
the operand field. This field cannot extend beyond column 71 of 
a model statement. The comments field can contain any 
combination of characters and it is passed to the expanded 
statement exactly as it appears in the model statement. Variable 
Symbols in a comment field have the value substituted. Example: 


NAME OPERATION OPERAND COMMENTS 


field field field field 


2-6-5 Using Symbolic Parameters in Model Statements 


A symbolic parameter is defined in the prototype statement and is 
assigned a value when the argument calls the macro. A symbolic 
parameter cannot have its value changed in the macro definition 
bodye It is always local to the macro definition; the same 
Parameter name can be in several macros. 


By varying values given to symbolic parameters, the user can vary 
the statements generated for each macro instruction. If a 
Symbolic parameter appears in a model statement, it must have 
been defined in the name or operand field of the prototype 
statement or an expansion error occurs. The following example 
demonstrates how the macro instruction operands that invoked the 
definition replace the symbolic parameters of the model 
statement: 
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NAME OPERATION OPERAND TYPE 


MACRO 1 
“NAME MOVE %FROM,%TO 2 
%NAME ST 1,HOLD 3 
1 1,%FROM 3 
St 1,%TO 3 
L 1,HOLD 
MEND . uy 
SYMBCL MOVE HERE, THERE 5 
SYMBOL ST... 1,HOLD 6 
ie. % 1,HERE 6 
ST 1,THERE 6 
L 1,HOLD 6 


LEGEND FOR TYPE COLUMN 


macro header 

macro prototype 
model statement 
Macro trailer 

macro instruction 
generated statement 


Au f& WN a 


2-6-5-1 Concatenation Rules 


A symbolic parameter in a model statement is concatenated with 
other symbolic Parameters or variable symbols immediately 
preceding or succeeding the symbolic parameter. An example is: 


ST%SUFF 4,%DEST%SUFF 


STZSUFF means concatenate ST with “%SUFF to form STH (when %SUFF 
is ‘H'). A%ADESTASUFF means concatenate Z2ZDEST with ZSUFF. 


NOTE 


The concatenation is implicit here. 


If a symbolic parameter is to be concatenated with a letter, 
number, or left parenthesis, the symbolic parameter must be 
immediately followed by a colon. In this case, the characters 
corresponding to the symbolic parameter replace the symbolic 
Parameter and colon. Carefully distinguish between array 
references or sublist notation and concatenation with a left 
parenthesis in a model statement: 
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oT 1,”4T0: (1) 


means concatenate %TO with ( to from THERE(1). 


ST 1,%2T0(1) 


is the first element of the array %TO. 


For a single colon to appear in a statement, use two consecutive 
colons. The following example illustrates the rules for 
concatenating symbolic parameters: 


NAME OPERATION OPERAND TYPE 
MACRO 1 
ANAME MOVE *ATY,%2FROM,2%TO, AX 1 2 
ANAME STATY 1,HOLD 3 
LATY 1,A2FROM:A 3 
STATY 1,%T0: (%X1) 3 
LATY 1,HOLD 3 
MEND 4 
SYMBOL MOVE H,HERE,THERE, 13 5 
SYMBOL STH 1,HOLD 6 
LH 1,HEREA 6 
STH 1,THERE(13) 6 
LH 1,HOLD 6 


LEGEND FOR TYPE COLUMN 


macro header 

Macro prototype 
model statement 
macro trailer 

macro instructicn 
generated statement 


Hof why 
Hounw t wou 
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CHAPTER 3 
WRITING MACRO INSTRUCTIONS 


3.1 INTRODUCTION 


A macro instruction is an instruction used to declare variables, 
and to assign values tc variables, unconditional branches, and 
conditional branches. The following sections detail rules for 
Writing macro instructicns, types of macro instructions, inner 
and outer macro instructions, and levels of macro instructions. 


3-2 RULES FOR WRITING MACRO INSTRUCTIONS 


The following sections explain the rules for writing macro 
instructions. 


3.2.1 Macro Instruction Name Field 


A name, if used in the macro instruction name field, does not 
appear in a generated statement unless a specific symbolic 
parameter appears in both the name fields of the prototype 
statement and expanded model statement. 


3.2.2 Macro Instruction Operation Field 


The operation field contains a mnemonic operation code. This 
code must be the same prototype statement code contained ina 
macro definition. This macro definition appears in a macro 
library, or it previously appeared in the source streame The 
Macro processor uses the applicable macro definition to determine 
the statements to be expanded to the assembler source strean. If 
a macro definition in the processor source stream and a macro 
definition in a macro library have the same mnemonic operation 
code, the definition in the source stream is processed. 


3-2-3 Macro Instruction Operand Field 


Any combination of characters can be used aS a macro instruction 
operand if these rules are followed: 


e A quoted string is a character sequence enclosed in paired 
apostrophes. The paired apostraphes are the first and last 
apostrophes ina quoted string. The first even numbered 
apostrophe, not immediately preceding another apostrophe, must 
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terminate a quoted string. If an apostrophe is used as a 
character in a quoted string, it must be expressed as two 
consecutive apostrophes. 


For example: 


- In the quoted string, ‘ABCDEF*, the apostrophes preceding 
the A and following the F are paired apostrophes. 


- In the quoted string, ‘DON''T’, the apostophes preceding 
the D and following the T are paired apostrophes. The 
apostrophes between the N and T generate a single 
apostrorhe as a part cf the string. 


Paired parentheses consist of a left and following right 
parentheses without any other intervening parentheses. If 
Faired parentheses are nested, identify each pair; then, find 
the left parenthesis and the following right parenthesis with 
no other intervening parenthesis. The maximum pairs of 
parentheses that can be nested is 15. When considering paired 
parentheses, ignore a single parenthesis enclosed in paired 
apostrophes. 


For examples 


- In the expression, (A-B), the parentheses preceding the A 
and following the B are paired. 


- In the expression, ((A*B)-C), the leftmost and rightmost 
parentheses are paired; the innermost parentheses are also 
paired. 


A percent sign (4) jidentifies a symbolic parameter unless it 
appears between paired apostrophes. Use two consecutive 
percent signs to ensure that a single percent sign appears in 
a statement. ! 


A comma (,) indicates the end of an operand, unless it is 
placed between paired apostrophes. . 


A blank indicates the end of the onerand field, unless it is 
Placed between paired apostrophes. 


A colon (:) indicates concatenation, unless it appears 


between paired apostrophes. Use two consecutive colons to 
ensure that a single colon appears in a statement. 
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3e3 MACRO INSTRUCTION OPERANDS 


A macro instruction invokes a given macro definition. Macro 
instructions take three forms: positional, keyword, or mixed 
modee These three forms correspond to the three forms of 
prototype statements. See Section 2.5.2. The macro instruction 
statement format is: 


NAME OPFRATION OPERAND 

Symbol or a mnemonic positional: zero or more 

blank operation operands separated by 
commas 
keyword: one or more 
operands separated by 
commas and consisting of 
a keyword, immediately 


followed by an equal sign, 
followed (optionally) by a 


value 
mixed modes positional 
operands followed by 


keyword operands 


@e Positional Macro Instructions 


- Ina macro instruction containing positional operands, the 
placement of the symbolic parameters in the operand field 
of the prototype statement determines the placement of 
operands. 


e Keyword Macro Instructions 


- A keyword operand is the portion of a symbolic parameter 
that does not include the percent sign. Anything that can 
be used as an operand value in a positional macro 
instruction can be used as a value ina keyword macro 
instruction. Each keyword operand ina macro instruction 
must consist of a keyword immediately followed by an equal 
sign (=), followed (optionally) by a value. 


- Operands ina keyword macro instruction can be written in 
any order or can be omitted. If a keyword operand is 
omitted, its delimiting comma can also be omitted. 


e Mixed Mode Macro Instructions 


- Ina mixed mode macro instruction, all positional operands 
must be placed before any keyword operands. 
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Example: 


NAME OPERATION OPERAND COLUMN 72 
symbol or MOVE A,B,LEN=80 blank 
biank 


In this example, A ang B are positional operands, and LEN=80 is 
a keyword operand. 


Apply these general rules to the operand field of a positional, 
keyword, or mixed mode macro instruction: 


e A comma must follow each operand, but a comma does not follow 
the last operand. 


e A single comma, followed immediately by another comma, 
indicates that an operand does not exist. 


e If a continuation character (Section 3.3.1) iS not present, 
use at least one blank space to indicate the end of the 
operand field. 


e Use a comma to indicate omitted positional operands. 


3.3.1 Continuation of Macro Instructions 

Macro instruction statements can be continued if the operand 
field extends beyond cclumn 71. To continue macro instruction 
statements: 

e Column 72 must contain a nonblank character. 


e Each operand can appear on a separate line. 


@e A comma must follow each operand except the last. 


The following example illustrates continuation of a macro 


instruction containing keyword operands: 


NAME OPERATION OPERAND COLUMN 72 
symbol or MOVE FROM=HERE, X 
blank | TO=THERE, X 

: BYTES=80 
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The following example illustrates continuation of a macro 
instruction containing mixed mode operands: 


NAME OPERATION OPERAND COLUMN 72 
symbol MOVE A, X 
B, LEN=80 


The guidelines for continuation lines, omitted positional and 
keyword operands, and operand sublists apply to mixed mode 
operations as they apply to positional and keyword operands, 
respectively. 


3.3.2 Omitted Operands 


These guidelines apply to omitted positional operands: 


e If an operand is omitted from a frositional macro instruction, 
the comma must be present. This comma represents the comma 
that would have separated it from the next value. 


e If the symbolic parameter corresponding to an omitted 
positional operand is referenced in an expanded model 
statement, a null character value replaces the symbolic 
parameter in the expanded statement. 


e If the last operand is omitted, the comma separating the last 
operand from the previcus operand can be omitted. 


These guidelines apply to omitted keyword operands: 


e If the prototype statement assigned a standard value to a 
symbolic parameter and the macro instruction does not contain 
the corresponding keyword, the standard value replaces the 
symbolic parameter. 


e If the prototype statement did not assign a standard value to 
a symbolic parameter and the macro instruction does not 
contain the corresponding keyword, a null character value 
replaces the symbolic rarameter. 


e If a symbolic parameter appears in the operand field of the 
prototype statement and the macro instruction contains the 
corresponding keyword, the value assigned to the keyword 
replaces the symbolic parameter. 
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3.3.3 


Sublists 


A sublist consists of one or more operands separated by commas 


and 


enclosed in paired parentheses. The entire sublist, 


including the parentheses, is one macro instruction operand. 


Positional Macro Qperand Sublists: 


- If “28P isa symbolic Parameter in a prototype statement and 


the corresponding operand in a macro instruction is a 
sublist, then: | 


”ASP(n) 


is used to reference the nth operand of the sublist; 
where n, which can be a decimal integer or any 
arithmetic expression that resolves a decimal integer, 
is greater than or equal to 1. 


If the nth operand of the sublist is omitted, then %SP(n) 
refers toa nujl character value. 


If the sublist ,notaticn is used, but the operand in the 
macro instruction is not a sublist, then %SP(1) refers to 
the operand and any other sublist notation references a 
null character. 


When using sublist notation, the left parenthesis must 
immediately fdllow the last character of the symbolic 
parameter. The following example illustrates the use of 
operand sublists: 
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Example: 


NAME OPERATION OPERAND TYPE 
MACRO 1 
ASYMBOL CLEAR AR1,AFI ELD, 2X2 2 
A2SYMBOL LIS %R1,0 3 
ST AR1,%2FTELD(1):(%X2) 3 
st %2R1,4FIELD(2): (2X2) 3 
of AR1,A2FIELD(3):(%X2) 3 
MEND 4 
CLRAREA1 CLEAR 6,(FLD,FLDA,FLDB),13 s) 
CLRAREA1 LIS 6,9 6 
ST 6,FLD(13) 6 
ST 6,FLDA(13) 6 
ST 6,FLDB(13) 6 


LEGEND FOR TYPE COLUMN 


macro header 
prototype statement 
model statement 
macro trailer 

macro instruction 
generated statement 


Am fe WN = 
how uo mal 


3-4 INNER/OUTER MACRO INSTRUCTIONS 


When mnemonic operation code for a given macro definition appears 
as the operation field of a model statement in another macro 
definition, the model statement (see Section 2.6) is an inner 
Macro instruction and the macro instruction referring to the 
containing definition is an outer macro definition. The macro 


definition that correspends to an inner macro instruction 
generates the Statements that replace the inner macro 
instructions. Recursion is permitted, and recursive macros 


expand properly. 


The corresponding values of the outer macro instructions replace 
the symbolic parameters used in an inner macro instruction. 


An inner macro instruction cannot reference a single member of an 
outer macro instruction sublist unless the inner macro 
instruction references the operand containing the entire sublist 
and the macro definition corresponding to the inner macro 
instruction contains a reference to the sublist member. 
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Keyword, positional, or mixed mode instructions can be used as 
model statements in keyword, positional, or mixed mode macro 
definitions. The following illustrates the use of inner macro 
instructions: 


STORE is an outer macro. 


ADD is an inner macro. 


NAME OPERATION OPERAND TYPE 


MACRO 1 
SSYM ADD AREG, ZFLD 2 
L AREG,/AFLD(1): (13) 3 
A . AREG,*FLD(2): (13) 3 
A AREG, AFLD(3) :(13) 3 
MEND 4 
MACRO 1 
STORE AR1,AFIELD,-A2ZR1A,A2FIELDA 2 
ADD ”ARIA,Z7FIELDA 3 
LR ”AR1,A4R1A 3 
ST AR1,4FIELD(1) 3 
ST | AR1,A4FIELD(2) 3 
MEND ; 
STORE 6,(F1,F2),7,(FA1,FA2,FA3) 5 
L 7,FA1(013) 6 
A 7,FA2(13) 6 
A 7,FA3(13) 6 
LR 6,7 6 
SL 6,51 6 
SL 6,F2 6 


LEGEND FOR TYPE CCLUMN 


Macro header 
prototype statement 
model statement 
macro trailer: 
Macro instruction 
generated statement 


Aon & Ww A = 


3.4.1 Levels of Macro Instructions 


A macro definition corresponding to an outer macro instruction 
can contain any number of inner macro instructions. The outer 
Macro instruction is a first level macro instruction. Each of 
the inner macro instructions is a second level macro instruction. 
A macro contained within the macro definition corresponding to a 
second level macro instruction is a third level macro 
instruction, etc. 
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The number of macro instruction levels that can be used depends 
on the definition's complexity and the amount of available 
MeEMOLryY. 


3.4.2 Macro Instructions in Conditional Assembly 


CAL conditional assembly, such as IFZ, IFNZ, cannot be evaluated 
at macro processing time since the values of EQUS are not known 
to the macro processor. Hence, any macros within conditional 
code will always be expanded, regardless of whether CAL will 
actually generate the expanded code. Normally, this would be no 
problem since CAL would not assemble the expanded code if the 
conditional failed. However, certain macros; eege, PURE, IMPUR, 
also set CAL macro global flags that are used by other macros. 
These flags are set regardless of whether CAL assembles the 
statements in the assembly. 


It is advisable not to use IFZ or IFNZ to generate such macros as 
PURE or IMPUR. 


Examples: 
FLAG EQU 0 
IFNZ FLAG 
PURE 
ENDC 


In the previous example, CAL will not generate the PURE 
statement; however CAL macro will set a global flag within the 
PURE macro, thus affecting other macros. An example of an 
alternate approach to code such a macro is: 


Examples 


MACRO 

SETFLAG 

GBLB AFLAG 
AFLAG SETB 0 


GBLB AFLAG 
SETFLAG 
AIF (%FLAG) &PURE 
MEXIT 
& PURE PURE 
MEND 


In the previous example, a call to ISPURE with &%FLAG set to 0 
will not generate the PURE statemente A call to ISPURE with 
“FLAG set to 1 will generate the PURE statement. 
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CHAPTER 4 
CONDITIONAL EXPANSION OF MACRO DEFINITIONS 


4.1 INTRODUCTION 


The following sections detail the conditional expansion of a 
macro definition. Global, batch global, and local SET variable 
symbol declaration statements, the SET variable symbol 
Statements, attributes, sequences symbols, and system variable 
symbols are discussed. 


4.2 GLOBAL, BATCH GLOBAL, AND LOCAL SET VARIABLE SYMBOL 
DECLARATION STATEMENTS 


Variable symbols, known as SET variable symbols, must be declared 
before they can be used. Variable symbols can be declared as: 


@e local to a given macro definition, 
@e global to all macro definitions in a program, or 


e ’ (batch) global to all macro definitions in all programs in the 
batch 


‘as they are invoked in a given macro processor pass. These 
symbols are declared by way of the global SET variable symbol 
(GBLx), batch global SET variable symbol (BGBLx), or local SET 
variable symbol (LCLx) declaration statements. Only a SETx 
instruction can change the SET variable symbol value. Section 
2e42.1-1 gives additional information on iad global, and batch 
global variable symbols. 
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4.2-1 Global SET Variable Symbol Declaration (GBLx) Statement 


The GBLx symbols communicate values between macro definitions or 
different uses of the same macro definition in a program. A GBLx 
symbol must be declared as global each time it is used in a macro 
definition. GBLA, | GBLB, and GBLC statements reference 
arithmetic, binary, and character variables, respectively, and 
assign values to them. The initial values of the GBLA, GBLB, and 
GBLC variable symbols are 0, 0, and null character values, 
respectively. The initial value is only assigned when a_ macro 
definition, which contains a particular global SET variable 
symbol, is first invoked. Subsequent GBLx instructions have no 
effect on the value assigned to a GBLx symbol. The format of the 
GBLx statement is: 


NAME OPERATION OPERAND 
blank GBLA, ¢BLB, or GBLC one or more variable 
symbols used as 
| global SET variable 
symbols, separated 


by commas 
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| BGBLx | 


4.2.2 Batch Global SET Variable Symbol Declaration (BGBLx) 
Statement 


The BGBLx symbols communicate values between programs in the 
batch. Within a program, BGBLx symbols perform the same function 
as GBLx symbols. A BGBILx symbol is initialized at the first 
declaration of that symbol in the batch. The initial values of 
the BGBLA, BGBLB, and BGBIC variable symbols are 0, 0, and null 
character values, respectively. The value assigned to the BGBLx 
symbol is available to all successive programs in which it is 
declared as a BGBLx symbol. The format of the BGBLx statement 
is: 


NAME OPERATION OPERAND 
blank BGBLA, BGBLB, one or more variable 
or BGBLC symbols used as batch 
global SET variable 
symbols, separated by 
commas. 


48-057 FOO ROO 4-3 


4.223 Local SET Variable Symbol Declaration (LCLx) Statement 


The LCLx symbols communicate values within the same usage of a 
particular macro definition. A local SET variable symbol is only 
declared in the macro) definition that it is used in. It is reset 
to its initial value] each time that macro definition is invoked. 
The initial values of} LCLx symbols are the same as those for 
global SET variable symbols (0, 0, and null character values). 
The format of the LCLx instruction is: 


NAME OPERATICN OPERAND 

biank LCLA, LCLB, or. LCLG one or more variable 
| symbols used as local 
| SET variable symbols, 


separated by commas 


4.2.4 Declaring SET Variable Symbols 


The following rules apply to declaring SET variable symbols: 


i 
{ 


e If the same SET variable symbol is declared local in more than 
one macro definition, it becomes a different symbol for each 
definition ‘in which it is used. 


e If the same SET variable symbol is declared global or batch 
Global in one or' more macro definitions and local in others, 
it is one symbol wherever it is declared global or batch 
global and a different symbol wherever it is declared local. 

e If the same SET variable symbol is declared batch global in 
one or more macro definitions and global in others, it is one 
Symbol wherever it is declared batch global and a different 
symbol wherever it,is declared global. 


All batch global, global, or local declarations must immediately 
follow the macro pfototyre statement or other BGBLx, GBLx, or 
LCLx statements. 
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4.2.5 Declaring SET Variables as Arrays 


A batch global, 


global, or local SET variable can be declared as 


an arraye The format is: 


NAME 


blank 


OPERATION OPERAND 

BGBLA, BGBLB, variable symbol followed 
BGBLC, GBLA, by an integer enclosed in 
GBLB, GBLC, parentheses 

LCLA, LCLB, 

or LCLC 


The integer is the highest subscript; the lowest subscript is 0. 
The number of elements is one greater than the integer dimension. 


Example: 


NAME 


blank 


CPERATICN OPERAND 


GBLA ZAR1(9) 


This statement declares a global arithmetic set variable %AR1 as 
an array of 10(=9+1) elements. 


Ten elements of %AR1 are %AR1(0),H%AR1(1) , eee, %AR1(9)- 
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a ap ee en ae ee em = 


| SETx {| 


4.3 SET VARIABLE SYMBOL (SETx) STATEMENTS 

The SETx statements alter the values of the variable symbols that 
the BGBLx, GBLx, or LCLx declaration statements declared as SET 
variable symbols. These SET statements assign arithmetic, 
character, and binary:or Boclean values to SETA, SETC, and SETB 
variables, respectively. 

Arithmetic expressions can be a Single term or an arithmetic 
combination of terms. The arithmetic operators used in combining 
terms ares: 

e addition (+), 

e subtraction (-), 

@e multiplication (*), and 

e division (/). 

An arithmetic expression cannot contain two operators or two 
terms in succession, nor can it begin with the multiplication or 
division operators. : This procedure evaluates arithmetic 
expressions: 


e Each term is given its numerical value. 


e The arithmetic operaticns are performed from left to right. 
Unary plus or minus is evaluated first. 


e Multiplication and division are performed before addition and 
subtraction. 


e Parentheses can be used to redefine the order of evaluation. 
Parenthesized sequences can be nested to a limit of 15 levels 


of parentheses. Parentheses required for sublist and 
substring notation count toward this limit of 15. The 
parenthesized portions or an arithmetic expression are 
evaluated first. If there is more than one level of 


parentheses, the inner-mcst level is evaluated first. 


e In division only, the integer portion of the quotient is 
retained; for example: 91/25 yields 3. If an expression 
exceeds the maximum range of values, it is flagged as an 
expansion error. 
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Section 4.3.1 details the relationship of arithmetic expressions 
to SETA statements. , 


These guidelines apply to character expressions: 


e The maximum number of characters that can be assigned to a 
SETC symbol is eight. . 


e A character expression ccnsists of a type attribute or any 
combination of up to 255 characters, enclosed in apostrophes. 


@e More than one character expression can be concatenated into a 
Single character expression by placing a colon between the 
terminating apostrophe of the first expression and the leading 
apostrophe of the next one. Use two apostrophes to represent 
an apostrophe that is a fart of a character string. 


e By specifying a specific character string, smaller substrings 
can be extracted from larger strings. 


Section 4.3.2 details the relationship of character expressions 
to a SETC statement. 


Binary or Boolean variables have the value of 0 (false) or 1 
(true). A binary variable can be assigned a value by evaluating 
a relational expression enclosed in parentheses. The value of 
the relational expression is either true or false. 


A binary variable can also be assigned a value as a result of 
logical comparisons. Both operands must be the same type; for 
example, both must be character expressionse Logical expressions 
can be formed by using the operations AND, OR, NOT. The 
expression is evaluated from left to right; AND is evaluated 
before OR. 


Section 4.3.3 details binary or Boolean values assigned to a SETB 
statement. 
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4.3.1 SET Arithmetic Variable (SETA) Statement 


The SETA instruction assigns an arithmetic value to a SETA symbol 
or array element. Its format is: 


NAME OPERATION OPERAND 


| 
a SETA ‘SETA an arithmetic expression 
symbol or 
array 
element 


The arithmetic eae Fics is evaluated as a signed 32-bit 
arithmetic value {in the range of -2,147,483,648 to 
+2,147,483,647. The value is assigned to the SETA variable 
symbol in the name field. The expression can consist of one term 
or an arithmetic combination of terms. The terms that can be 
used are: 


@e signed integer constants, 
® variable symbols, 
e count attributes, and. 


@® number attributes. 
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4.3.1.1 Using SETA Variable Symbol 


When using a SETA variable symbol, its assigned arithmetic value 
is substituted for the SETA symbol when the symbol is used in an 
arithmetic expression. If the SETA symbol is not used in an 
arithmetic expression, the arithmetic value is converted to a 
Signed integer with leading zeros removed. If the value is zero, 
it is converted to a single zero. A SETA variable symbol (with 
a positive value) can be used with a symbolic parameter to refer 
to an operand in a sublist or array vehicle. This example 
illustrates the use of SETA variable symbols: 


NAME OPERATION OPERAND TYPE 
MACRO 1 
MVBYT %ATO=, AF ROM=,2REG=13 2 
LCLA ZALOC(2) 3 
AALOC( 1) SETA 1 4 
*ZALOC(2) SETA AALCC(1)+%ZAL0C(1) 4 
LB AREG, 4FROMZALOC(1) 5 
STB AREG, ATORALOC( 2) 5 
MEND 6 
MVBYT FROM=HERE, TO=THERE 7 
LB 13,/HERE1 8 
STB 13,THERE2 8 


LEGEND FOR TYPE COLUMN 


macro header 

macro prototype 
local declaraticn 
SETx instruction 
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macro trailer 

macro instruction 
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4.3.2 SET Character Variable (SETC) Statement 


The SETC statement assigns a character value to a SETC variable 
symbol. The format of the SETC statement is: 


NAME OPERATICN | OPERAND 


a SETC symbol SETC one operand consisting of a 
Or array element type attribute, Character 


expression, substring notation, 
or a concatenation of substring 
notations and character 
expressions 


If a SETA symbol appears in the operand of a SETC statement, the 
resulting unsigned character represents the decimal value, with 
leading zeros removed. If a SETB symbol appears, the result is 
the character 0 or 1. 


Variable symbols can be concatenated with other characters in a 
SETC operand. Use two percent signs to represent a Single 
percent sign that is not fart of a variable symbol. 


The maximum number of characters that can be assigned to a SETC 
symbol is 8. 


4.3.21 Substring Notation 


Substring notation allows assigning a part of a character value 
to a SETC variable symbol indicating in the operand field of a 
SETx statement: 


e the character value or an expression representing the 
character value, and 


e the part of the character value to be assigned to the SETC 
variable symbol. 


The combination of the previous items, referred to as substring 
notation, consists of a character expression, immediately 
followed by two arithmetic expressions separated by a comma and 
enclosed in parentheses. The two arithmetic expressions indicate 
the beginning and ending characters in the substring. Positive 
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values refer to the beginning of the string; negative values 
refer to the end of the stringe This example illustrates the use 
of substring notation: 


NAME OPERATION OPERAND 
*%CLOC1 SETC *BASEADDR' 
*CLOC2 SETC "%CLOC1°(1,4) 
*CLOC3 SETC °*%CL0C1' (5,71) 
In the previous example, the character value, *BASEADDR'‘* is 


assigned to the SETC variable, %CLOC1. The character values 
"BASES and ‘ADDR* are assigned to the SETC variables %CLOC2 and 
”ZCLOC3 respectively. 


If a substring requests mcre characters than are contained in the 
character string, only the characters in the string are assigned. 
The maximum size of a substring is 255 characters. The maximum 
size of the expression the character value is developed from is 
255 characters. 


Character variables and substring notation are valuable in 
scanning arguments for occurrences of quotes, parentheses, or 
special characters. 


4.32-2-2 Using SETC Variable Symbols 


The character value assigned to a SETC symbol is substituted for 
the SETC symbol when it is used in the name, operation, or 
operand field of a statement. 


Character expressions can be concatenated with substring 
notations in the operand field of a SETC instruction. If a 
substring notation follows a character expression, the two can be 
concatenated by placing a colon between the terminating 
apostrophe of the character expression and the opening apostrophe 
of the substring notation. If a subsString notation precedes a 
character expression or another substring notation, the colon is 
not necessary for concatenation. 


If a SETC variable symbol is used in the operand field of a SETA 
instruction, the character value of the SETC symbol must be one 
or more decimal digits; or, it is flagged as an expansion error. 
This example illustrates the use of the SETC variable statements: 
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NAME OPERATION OPERAND 
MACRO SAVE REGISTERS 
SAVE, %REG 
LCLA %ZALOC 
ECLC “REGS, %REGS1,%REGS2 
%ALOC SETA : %REG 
%REGS SETC | "R's *%ALOC' 
%ALOC SETA | %ALOC+#1 
%REGS SETC "AREGS': "R's *%ALOC! 
YALOC SETA %ALOC+1 
% REGS SETC "ZREGS': "R's" ZALOC' 
%ALOC SETA : %ZALOC+1 
@ REGS SETC | "ZREGS's*R*s"%ALOC* 
ZREGS 1 SETC "ZREGS' (1,2) 
ZREGS 2 SETC "%ZREGS' (2,2) 
ST %REGS1,HOLD%REGS2 
%REGS1 SETC . "ZREGS' (3,4) 
%REGS2 SETC *ZREGS1'( 2,2) 
ST %REGS1,HOLD%ZREGS2 
%REGS 1 SETC | "ZREGS' (5,6) 
%REGS2 SETC "*AREGS1'(2,2) 
ST . %REGS1,HOLD%REGS2 
%REGS 1 SETC "2REGS' (7,8) 
%REGS2 SETC "%ZREGS1°( 2,2) 
ST | %REGS1,HOLDZREGS2 
MEND | 
SAVE | 2 
ST ! R2,HOLD2 
ST . R3,HOLD3 
ST | R4G,HOLD4 


ST | R5,HOLDS 


LEGEND FOR TYPE COLUMN 


macro header 

macro prototype 
local declaration 
SETA statement 

SETC statement 
model statement 
macro trailer 
macro instruction 
generated statement 
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The previous example defines the macro ‘SAVE'. When the macro 
SAVE is invoked, it generates assembly code to save four 
registers beginning with the register designated in the operand 
field of the macro instruction. 


The macro instruction ‘SAVE2° generates assembly code to save 
registers 2 through 5 in the memory locations designated HOLD2 
through HOLDS. This operation is accomplished by first building 
a character local variable containing ‘R2R3R4R5* and using 
concatenation and substring notation to expand the proper values 
to the generated assembly code. 


To build the assembly instruction, ‘ST R2,HOLD2', this procedure 
is used: 


1.2 The character string ‘R2R3R4UR5' is built in “ZREGS. 


2.- The statement "Z%ZREGS1 SETC ‘"ZREGS*(1,2)" extracts the first 
two characters (or ‘R2') from %ZREGS and places them in 
AREGS1. 


3. The statement "ZREGS2 SETC ‘ZREGS1#'(2,2)" extracts the second 
character (or '2') from ZREGS1 and places it in ZREGS2. 


4. In the model statement “ST ZREGS1,HOLDZREGS2", R2 is 
substituted for %ZREG1 and 2 is substituted for “ZREGS2 and 
concatenated with HOLD to form HOLD2. The resulting 
statement is "ST R2,HCLI2". 
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4.3.3 SET Binary Variable (SETB) Statement 

The SETB statement asgigns the value true (binary 1) or false 
(binary 0) to a SHTB variable symbol. The format of the SETB 
instruction is: 


NAME OPERATION OPERAND 
a SETB SETB a 0 or 1 or Ilogical 
symbol or , expression enclosed in 
array element ; parentheses 
A logical expression consists of one term or a logical 


combination of terms. The terms that can be used are: 


e arithmetic relations, 


e character relations, and 


e SETB variable symbols. 
| 
| 


The logical operators used in combining the terms are OR, AND, 
and NCT. | 


A logical operator must always separate a logical expression that 
contains two consecutive terms. The expression can contain two 
successive operators only if the first operator is OR or AND, and 
the second operator is NOT. A logical expression can begin with 
the operator NOT; but, it cannot begin with OR or AND. A logical 
expression is evaluated to determine if it is true or false; the 
SETB variable symbol is then assigned the value of 1 or 0. 

An arithmetic relation consists of two arithmetic expressions 
enclosed in parentheses, connected by a relational operator. A 
character relation consists of two character values enclosed in 
apostrophes connected by a relational operator. The six 
relational operators are: . 


e EQ is equal. 
e GE is greater than or equal. 
e GT is greater than. 

e LE is less than or equal. 

e iT is less than. 


e NE is not equal. 
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At least one blank must precede and succeed the relational and 
logical operators. 


Any arithmetic expression permitted in the operand field of a 
SETA instruction can be used in the operand field of a SETB 
instruction as a part of an arithmetic relation. 


Any expression permitted in the operand field of a SETC 
instruction can be used as a character value in the operand field 
of a SETB instruction. In resolving a SETB expression using 
character relations, two character values are considered equal 
only when they are of equal length and contain the same 


characters; for example: *Z0° is less than "020°. When two 
Character values are of unequal length, the shorter value is 
always less then the longer one; that is: ‘Z' is less than ‘AAS. 


Logical expressions are evaluated as follows: 


e Each term is evaluated and given its logical value. 


e Each parenthesized expression is evaluated and given its 
logical value. 


e The computed result of the entire operand (1 for true, 0 for 
false) is the value assigned to the SETB variable symbol. 


The logical expression in the operand field of a SETB instruction 
can be parenthesized. Parenthesized sequences of terms can be 
nested to a limit of 15 levels of parentheses. The parenthesized 
portions of a logical expression are evaluated first. If there 
is more than one level of parentheses, the innermost level is 
evaluated first. 


4.3.3.1 Using SETB Variable Symbols 


The logical value assigned to a SETB variable symbol replaces the 
SETE symbol in the operand field of a conditional instruction or 
another SETB instruction. If a SETB symbol appears in the 
operand field of a SETA instruction or in arithmetic relations in 
the operand fields of conditional or SETB instructions, the 
logical values 0 and 1 are converted to the arithmetic values +0 
and +1. If a SETB symbol appears in the operand field of a SETC 
instruction or ina character relation in the operand field of a 
conditional or SETB instruction, the logical values 0 and 1 are 
converted to the character values 0 and 1. This example 
illustrates the use of the SETB instructions: 
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NAME OPERATICN OPERAND 


MACRO 
MOVE %FROM,%TO 
LCLA AALO1 
LCLB %BLO1 
LCLE %CLO1 
%BLO1 SETB  ("RFROM' NE '%TO') 
%*ALO1 SETA %BLO1+1 
%CLO1 SETC ‘A *(%AL01,%AL01) 
T,..'y 13,%FROM%CLO1 
ST | 13,4T0 
MEN D 
MOVE HERE,HERE 
iL 7 13,HERE 
St 13,THERE 
MOVE HERE, THERE 
i 4 13,HEREA 
ST | 13,HERE 


LEGEND FOR TYPE COLUMN 
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If an inner macro instruction operand is a symbolic parameter, 
the operand attributes are the same as those of the corresponding 
outer macro instruction cperand. A symbol appearing as an inner 
Macro instruction operand is not assigned the same attributes as 
the same symbol appearing as an outer macro instruction operand. 
Section 3.4 details inner and outer macro instructions. 


If a macro instruction operand is a sublist, the attributes of 
the sublist or each element in the sublist can be referenced. 
Section 3.3.3 details sublists. 


4.4.1 Type Attribute (T‘) 


The type attributes of the macro instruction operand are: 


e The letter A represents an alphanumeric operand. 


e The letter N represents a numeric operand. (A signed integer 
is recognized as numeric.) 


e The letter U represents a null operand. 


The type attribute can be used wherever a character expression 
could be used; but, the type attribute must occur alone (that is, 
not concatenated with anything), and it must not be enclosed in 
quotes. 


4.4.2 Count Attribute (K') 

The count attribute value is the number of characters in a macro 

instruction field. It includes all characters in the operand 

except the delimiting commas. The count attribute of an omitted 

operand is zero. The count attribute can be referred to: 

e in the operand field of a SETA instruction, or 

e in arithmetic relations in the operand fields of SETB, or 
conditional instructions in a macro definition. 

4.4.3 Number Attribute (N‘) 

The number attribute is a value equal to the number of operands 

in an operand sublist. The number is equal to one plus the 


number of delimiting commas within the sublist. If the macro 
instruction operand is not written in sublist notation, the 
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number attribute is one. If the operand is omitted, the number 
attribute is zero. The number attribute can be referred to: 


@e in the operand field of a SETA instruction, or 
e in arithmetic relations in the operand fields of SETB or 
conditional instructions ina macro definition. 


This example illustrates attributes: 


Given this macro prototype and instruction: 
MOVE  %REGC,%FROM,%TO,%HCLD 


MOVE 13,HERE, (THERE1, THERE2) 


T° %REG = N kK" AREG = 2 N*%REG = 4 
T°%FROM = A i'%FROM = 4 N°%FROM = 1 
T*ZTO = A Ki" %TO = 15 N'%TO = 2 
T'%HOLD = U K*%ZHOLE = 0 N*%HOLD = 0 
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4.5 CONDITIONAL AND UNCONDITIONAL BRANCH INSTRUCTIONS 

The conditional and unconditional branch instructions 
conditionally and unconditionally alter the macro definition 
processing sequence. 

4.5.1 Conditional Branch (AIF) Instruction 

The AIF instruction conditicnally alters the macro definition 


statement processing sequence. Its format is: 


NAME OPERATION OPERAND 


a sequence AIF logical expression enclosed 

symbol or in parentheses, immediately 

blank followed by a sequence 
symbol 


Any expression used in a SETB instruction operand field can be 
used in an AIF instruction operand field. The expression is 
evaluated to determine if it is true or false. If the expression 
is true, the statement that the sequence symbol in the operand 
field named is the next statement processed. If the expression 
is false, the next sequential statement is processed. Section 
4.7 gives examples of the AIF instruction. Section 2.4.3 details 
sequence symbols. 
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4.5.2 Unconditional Branch (AGO) Instruction 


The AGO instruction unconditionally alters the macro definition 
statement processing sequence. Its format is: 


NAME OPERATION OPERAND 
a sequence AGC a sequence symbol 
symbol or . 
blank 


The statement the sequence symbol names in the operand field is 
the next statement processed. 


The sequence symbol in an AGO or AIF instruction operand field 
must appear in a statement name field in the same macro 
definition as the AGO} or AIF instruction; or, it causes an 
expansion error. Section 4.7 gives examples of using the AGO 
instruction. 


4.5.3 Computed AGO and AIF Statements 


An AGO or AIF statement operand is extended to include a: 


@ character variable, 
@® array element, or 


@e parameter. 


The value of the character variable, array element, or parameter 
must be a valid sequence number. 
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Example: 


z”aC 
&AGAIN 


&SEQSYM 
”C 


ESEQ2 


The 
the 


&ABC 


&DEF 


takes a branch 


takes a branch 
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ANOP 
SETC 
AGO 

ANOP 


character value %C is redefined to &SEQ2. 
AGO is executed, 


MACRO 


EX2 
AGO 


aC 
"ESEQSYM' 


”C 


*ESEQ2° 
GAGAIN 


The 
a branch to 6&SEQ2 is executed: 


hP 
*P 


EX2 G& ABC 


to &ABC, while: 
EX2 &DEF 


to &DEF. 


second 


time 


The ampersand must be included in the macro call parameter. To 
avoid the ampersand in the macro call, use a string variable and 
concatenate the amperisand in the macro definition. Many of the 
system macros use this technique for codes: 


MACRO 
EX3 


CEC. 


%C SETC 
AGO 


&SRO ANOP — 


ESRW ANOP | 


”AF= 

aC 

"E*s "RAPS 
AC 
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4.6 CONDITIONAL INSTRUCTION LOOP COUNTER (ACTR) INSTRUCTION 


The maximum count of AIF and AGO branches that can be executed in 
a macro definition is 32767. The ACTR instruction assigns a 
count other than 32767 as the maximum number of AIF and AGO 
branches executed within a macro definition. The format of the 
ACTR instruction is: 


NAME OPERATION OPERAND 

blank ACTR. any expression that can appear 
in the operand field of a SETA 
instruction 


The ACTR instruction can only appear immediately after global and 
local declaration statements. This instruction causes a counter 
to be set to the value in the operand fielde The counter is 
checked for zero or negative value; if the counter is not zero or 
negative, it is decremented by one each time an AIF or AGO branch 
is executed. If the count is zero before decrementing, the 
entire nest of macro definitions is terminated and the next 
source statement is processed. An ACTR statement in a macro 
definition affects only the definition in which it appears. 


When a macro definition calls an inner macro definition, the 
current value of the branch count is saved and a new count of 
32767 is set up for the inner macro definition (unless the inner 
Macro contains an ACTR instruction). When processing in the 
inner definition is completed and a return is made to the higher 
definition, the saved count is restored. 
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4.7 NO OPERATION (ANOP) INSTRUCTION 


When the sequence symbol in an AIF or AGO instruction must 
reference a statement already containing a symbol (other than a 
sequence symbol) in the name field, the ANOP instruction is used. 
The format of the ANOP instruction is: 


NAME OFERATION OPERAND 
a sequence ANOP blank 
symbol 


The ANOP instruction is placed before the statement that the 
branch is to be made to and the sequence symbol is placed in the 
ANOP instruction name} field. This placement has the same effect 
as branching to the statement immediately following the ANOP 
instruction. The following example shows the use of conditional 
instructions: | 


i 
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NAME OPERATION OPERAND 


MACRO 
SAVE %ZREG,ZHOWMANY 
LCLA RAALOC,ZALCC1 
LCLC AREGS 
AIF ((T*AREG NE "N*) AND 
(T'AREG NE *U'))&END 
AIF ((T'XHOWMANY NE 'N‘) AND 
(T°AHOWMANY NE*U'))&END 
AIF ( NOT (CAREG GE O) AND 
(AREG LE 15)))&END 
AIF (T'ZHOWMANY EQ ‘U* )ENULL 
AIF ( NOT (CAHOWMANY GE 1) AND 
(ZHOWMANY LE 16)))&END 
& NULL ANOP 
AIF (T*AREG EQ *U*)&ZERO 
AALOC SETA %REG 
& ZERO ANOP 
AIF (T*ZHOWMANY EQ ‘N*)€ENOTALL 
*AALOC1 SETA 16-ZALOC 
AGO &CKSIZE 
ENOTALL ANOP 
AKLOC1 SETA AHOWMANY 
&CKSIZE AIF (ZALOC+ZALOC1 GT 16)&END 
ESETNAME ANOP 
AREGS SELG "R's *ZALOC® 
ot *AREGS,HCLOZALOC 
*ALOC1 SETA %ZALOC1~-1 
AIF (ZALOC1 EQ 0) &END 
AALOC SETA %ALOC+1 
AGO &SETNAME 
& END ANOP 
MEND 


LEGEND FOR TYPE COLUMN 
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The previous example defines the macro SAVE. This macro 
generates assembler code to save a number of registers 
(designated by “ZHOWMANY in the prototype statement) beginning 
with the register designated by “REG. If the argument used in 
Place of “ZREG is omitted in the macro instruction, RO is assumed 
to be the beginning register. If the argument used in place of 
*”HOWMANY is omitted in the macro instruction, it is assumed that 
all registers beginning with ZREG are to be saved. These 
examples show some possible expansions of the SAVE macro: 


NAME OPERATION OPERAND TYPE 


SAVE 10,4 1 
ST R10,HOLD10 2 
ST R11,HOLD11 2 
ST R12,HOLD12 2 
ST R13,HOLD13 ?, 
' SAVE 13 1 
ST R13,HOLD13 2 
ST R14,HOLD14 2 
ST R15,HOLD15 2 
SAVE “oD 1 
ST RO,HOLDO 2 
ST R1,HCLD1 2 


LEGEND FOR TYPE COLUMN 


macro instruction 
generated statement 


NO 
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4.8 MACRO DEFINITION EXIT (MEXIT) INSTRUCTION 


The MEXIT instruction terminates — the current macro definition 
expansion. Its format is: 


NAME OPERATION OPERAND 


a sequence MEXIT | not used 
symbol or 
blank 


If a MEXIT instruction is processed in a macro definition for an 
outer macro instruction, the next statement in the source is 
processed next. If a MEXIT instruction is processed in a macro 
definition for an inner macro instruction, the next statement 
after the inner macro instruction in the macro definition is 
processed nexte Section 3-4 details inner and outer macro 
instructions. This example illustrates the use of the MEXIT 
instruction: 


NAME OPERATION OPERAND TYPE 
MACRO 1 
AOYM MOVE AFROM,%TO,A4REG, AHOLD 2 
AIF (T'ZREG EQ 'N')&OK 3 
MEXIT 4 
G0K ANOP 5 
ASYM ST AR EG, AHOLD 6 
L AREG,;AFROM 6 
ST AREG,ATO 6 
L AREG, AHOLD 6 
MEND 7 


LEGEND FOR TYPE COLUMN 


macro header 

macro prototype 
conditional branch 
Macro exit 

no operation 

model statement 
Macro trailer 
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In the previous example, a numeric argument must represent the 
symbolic parameter #%REG when the macro instruction is written. 
To assure this representation, the %REG type attribute is 
compared to ‘N*. If it is not 'N', the MEXIT instruction is 
executed, resulting in the termination of any further macro 
expansion. : 
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4.9 REQUEST FOR MESSAGE (MNOTE) INSTRUCTION 


The MNOTE instruction generates a macro message. Its format is: 


NAME OPERATION OPERAND 
a sequence MNOTE an optional integer expression 
symbol or followed by a comma, followed 
blank by any combination of characters 


enclosed in apostrophes 


The characters between the apostrophes are printed on the source 
listing when the MNOTE instruction is processed. If a symbolic 
parameter appears between the apostrophes, its value replaces it 
when the message is printed. 


Use two apostrophes to represent a single apostrophe to be 
printed as part of the message in the source listing. Use two 
percent signs to represent a single percent sign to be printed as 
part of the message in the source listing. Use two colon signs 
(33) to represent a single colon sign to be printed as part of 
the message in the source listing. MNOTE statements can have a 
maximum of two continuation statements. 


The optional integer expression is the end of task code returned 
when the macro processor terminates. The default value for this 
integer expression is 0- The highest value that any executed 
MNOTE statement specifies is the value returned. This example 
illustrates using the MNOTE instruction: 
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NAME 


CPERATICN CPERAND 

MACRO 

MOVE AEROM,%TO,%ZREG, AHOLD 
AIF (T'*%REG NE *N*)&E2 

AIF (T°'ZHOLD FQ 'U')&EE1 

ST %ZREG,%HOLD 

L : %REG,%FROM 

ST %ZREG,&TO 

L %ZREG, %HOLD 

MEXIT 

MNOTE 8,°SAVE AREA NOT DEFINED* 
MEXIT 

MNOTE | 4,*REGISTER NOT NUMERIC’ 
MEND | 

MOVE | FROM,TO,REG,HOLD 

MNOTE "REGISTER NOT NUMERIC’ 
MOVE HERE,THERE, 4 

MNOTE | "SAVE AREA NOT DEFINED‘ 


The end of task code is 8. 


LEGEND FOR TYPE COLUMN 
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4.10 SYSTEM VARIABLE SYMBOLS 

The macro processor automatically assigns values to system 
variable symbols. These system variable symbols are local 
variable symbols. The five variable symbols: 

e %SYSLIST 

@e@ *ASYSINDX 

@ ASYSMAC 

@ %SYSTIME 

@ *SYSDATE 

can be used in the name, operation, or operand fields of 
statements in macro definitions. System variable symbols cannot 
be defined as symbolic parameters or SET symbols. Although these 
system symbols are the only system symbols defined at this time, 


do not use any variable symbol that starts with %SYS because of 
future expansion. 
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| %SYSLIST | 


4.10.1 &SYSLIST Symbol 


ASYSLIST provides an alternative to symbolic parameters for 
referring to positional macro instruction operands. Both 
“SYSLIST and symbolic frarameters can be used in the same 
positional macro definition. 


“@SYSLIST (n) refers to the nth positional macro operand. If the 
nth operand is a sublist, then %SYSLIST (n,m) refers to the mth 
operand in the sublist. Any arithmetic expression allowed in a 
SETA instruction operand field can represent n and Mm. 


If the value of n is zero, then &SYSLIST (n) is assigned the 
value specified in the macro instruction name field, unless that 
value is a sequence symbol. 


The type and count attributes of &SYSLIST(n) and AZSYSLIST(n,m) 
and the number of attributes of ZSYSLIST(n) and ZSYSLIST can be 
used in conditional instructions. N*ASYSLIST refers to the total 
positional operands. in a macro instruction statement. 
N*%SYSLIST(n) refers to the number of operands in a sublist. If 
the nth operand is null, n is zero. If the nth operand is not a 
sublist, N' is one. The following example illustrates the use of 
“ASYSLISTs 
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NAME OPERATION OPERAND TYPE 
MACRO 1 
ASYM MOVE AFRCOM,%2TO,AZREG, AHOLD 2 
LCLA ”AL1 3 
%AL1 SETA 1 
tC1610 AIF C'ASYSLISTCZAL1)° EQ °*')&ERR 4 
%AL 1 SETA AAL1+1 5 
AIF (ZAL1 LE 4) &CKNUL 4 
AGO &OK 6 
&ERR MNOTE *"PARAMETERZAL1 MISSING‘ 7 
MEXIT 8 
&0K ANOP 9 
STA *AREG, AHOLD 10 
LDA %REG, AFROM 11 
STA AREG, ATO 10 
LDA ”AREG, AHOLD 10 
MEND 11 
MOV 1 MOVE HERE, THERE, 13 12 
* MNOTE ‘PARAMETER 4& MISSING‘ 12 
LEGEND FOR TYPE COLUMN 
1 = macro header 
2 = macro prototyre 
3 = local declaraticn 
4 = conditional branch 
5 = SETA 
6 = unconditional branch 
7 = macro note 
8 = macro exit 
9 = no operation 
10 = model statement 
11 = macro trailer 
12 = generated statement 
The use of “*ZSYSLIST in the previous example avoids having to 
write a separate conditional branch instruction to check each 


argument for a null conditicn. 
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4.1002 %SYSINDX Symbol 


The value of the “SYSINDX variable symbol can be concatenated 
with other characters to create unique names for statements 
generated from the same mcdel statement. %Z5SYSINDX is assigned 
the numerical value for the first macro instruction that the 
macro processor procelsses. It is incremented by one for _ each 
subsequent macro instruction processed, whether inner or outer. 
If *SYSINDX is used’ in a model statement, SETC, or MNOTE 
instruction or in a character relation in a SETB or AIF 
instruction, the value sutstituted for %ZSYSINDX is the number of 
the macro instruction being processed. If “SYSINDX appears in an 
arithmetic expression, the value used for %SYSINDX is an 
arithmetic value. Throughout one use of a macro definition, the 
”ZSYSINDX value is constant, independent of any inner macro 
_instruction in that definition. The following example 
illustrates the use of Z%SYSINDX: 
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NAME OPERATICN OPERAND 

MACRO 
ASYM MOVE AFROM,A”ZTO 
ASYM STA 13,HOLDZSYSINDX 

LDA 13,%4FROM 

STA 13,4T0O 

LDA 13,2ZHOLDZSYSINDX 

B HOLDASYSINDX+ADC 
HOLDASYSINDX DAC 0 

: MEND 

MOV1 MOVE ASLOT,BSLOT 
MOV1 STA 13,HOLDO001 

LDA 13,ASLOT 

STA 13,BSLCT 

LDA 13,HOLDO0001 

B HOLDOOO1+ADC 
HOLDOOO1 DAC 0 
MOV2 MOVE XSLOT,YSLOT 
MOV2 STA 13,HOLD0002 

LDA 13,XSLOT 

STA 13,YSLCT 

LDA 13,HOLDO002 

B HOLDOO2+ADC 
HOLDOO002 DAC 0 


LEGEND FOR TYPE COLUMN 


macro 
macro 
model 
macro 
macro 


NOFwWN A 
hou Wow ou 


header 
prototype 
statement 
trailer 
instruction 


generated statement 


In the previous example, the variable symbol 
concatenated with the letters HOLD to form a unique label each 
time the macro is invoked. 
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TYPE 


NR) 2 


eww Www ee) 


ui 


ASYSINDX 


is 


4.10.3 ASYSMAC Symbol 


The system variable LISYSMAC differs from the system variable 
”SYSINDX because the inner macro calls change their value. Upon 
returning from an inner macro call, &%SYSINDX returns to its 
original value; while, %“SYSMAC remains at the incremented value 
because of the inner macre. An example of this useful feature 
is: INNER generated a label using “SYSMAC which was referred to 
in CUTER by using ZSYSMAC. This example shows the relationship 
between %SYSINDX and %2SYSMAC: 


NAME OPERATION OPERAND TYPE 
MACRO 1 
INNER 2 
IMPUR 3 
HOLD%SYSINDX DAS 1 3 
PURE 3 
MEND rr 
MACRO 1 
ASYM MOVE %FROM,%TO 2 
INNER 5 
%SYM STA 13,HOLD%SYSMAC 3 
LDA 13,%FROM 3 
STA 13,%TO 3 
LDA 13,HOLD%SYSMAC 3 
MEND mM 


LEGEND FOR TYPE COLUMN 


macro header 
macro prototype 
model statement 
macro trailer 
inner macro ¢all 


in ely Na 
HoT OW othe at 
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ASYSINDX ASYSMAC NAME OPERATION 


MOVE 
INNER 
IMPUR 
HOLDOCO2 PAS 
PURE 
STA 
LDA 
STA 
LDA 
MOVE 
INNER 
IMPUR 
HOLDOOO4 DAS 
PURE 
STA 
LDA 
STA 
LDA 


WWHWwWw Pre FWA a BP ANN DNN = 
SrPEF EHF HEP EWNNNNNNNDN 


NOTE 


OPERAND 


A,B 


1 


13,HOLDO0002 
13,A 

13,B 
13,HOLD0002 
C,D 


1 


13,HOLDO004 
13,C 
13,D 
13,HOLDO004 


After the inner call, “£SYSMAC retains its 


value. 
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| KSYSTIME | | 
| ZSYSDATE | | 


4.10.4 %SYSTIME Symbol 
ASYSTIME is an eight character string system variable whose value 


P j | : 
is the time of day that the macro processor was invoked. System 
generation determines; the fcrm. 


4.10.5 %SYSDATE Symbol 


ASYSDATE is an eight character string system variable whose value 
represents the date that the macro processor was invoked. System 
generation determines the form. 
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4.11 AREAD STATEMENT 


The syntax for the AREAD statement is: 


ASYMBOL AREAD 


wheres: 


*SYMBOL is a character variable or array variable large 
enough to contain the character string (a minimum of 80 
characters). 


When a macro containing an AREAD is called, the next source line 
is read into the character variable. The string handling 
capability of the macro processor can be used to process’ the 
line. The following macro demonstrates this capability: 


MACRO 
REED 
LCLC %C(9) 80 characters 
ZC AREAD READ NEXT-LINE AFTER CALL 
AIF (°%C°' (1,2) EQ ‘CR*)E&BYTE check for character 
DB X*00° NOT CR 


EBYTE ANOF 


+ DB X'OD° 
REED 


+ DB X"00'° 
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4.12 SUBSTRING NOTATION IN MODEL STATEMENTS 


Substring notation is allcwed in model statements. The following 


Macro demonstrates this capability: 


MACRO 
EXAMPLE 
LLC 

“TYPE SETC 
ALF 
BETYPE<2,2>C 
MEXIT 

ETRUE B&TYPE<1,1>C 
MEND 


wheres: 


EXAMPLE 
+ BTC 

EXAMPLE 
+ BEC 


NOTE 


Because . off possible 


AP 

ATYPE 

‘TFS 

(‘%P* EQ ‘'T')ETRUE 
ALPHA 


BETA 


ambiguities in 


interpretation, substring notation in a 
model statement always applies only to 
the immediately preceding symbolic 


variable or parameter 


quotes. 


not enclosed in 
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CHAPTER 5 
ADDITIONAL CAL MACRO/32 FEATURES 


5-1 INTRODUCTION 


The operation codes of the features discussed in this section are 
macro processor pseudo operation codes. Because they are macro 
processor pseudo operation codes, the processor recognizes and 
acts on them so they are not passed to the assembler source 
stream. 


48-057 FOO ROO a= 1 


5.1.1 As Is (ASIS) Instruction 


The ASIS instruction tells the macro processor not to treat the 
next line or lines| as macros even though these lines might be 
macros. This feature is useful when a macro is used to redefine 
a CAL operation code. The format of the ASIS instruction is: 


NAME OPERATION OPERAND 
| 
sequence ASIS, blank, decimal integer, BEGIN, 
symbol or END 
or blank 


Blank indicates the next statement only. Decimal integer means 


the next on statements. BEGIN means until an ASIS END is 


encountered. END indicates termination of ASIS BEGIN. 


The END statement does not cause termination of a macro expansion 
if it appears within an ASIS statement. 


The following instructions cannot occur in the scope of ASIS: 


ACTR BGBLC LCLC MEXIT NOLIB 
AGO GBLA MACRO MLIBS NTRAC 
AIF GBLB MCALL MNOTE SETA 

ANOP GBLC MCOPY MPAUSE  SETB 

BGBLA  LCLA MDEFS  MTRAC SETC 

BGBLB LCLB MEND NDEFS 
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521-2 Macro Call (MCALL) Instruction 


The MCALL instruction permits the cited macros to be called as 
they appear in the library rather than as they appear in the 
processor source stream. This method avoids time-consuming 
rewinds in a magnetic tape search or multiple disc access ina 
disc search. The format of the MCALL instruction is: 


NAME OPERATION OPERAND 


blank MCALL MACRO,MACRO,.--,MACRO 


A particular order does nct have to be specified in the MCALL 
instruction; the specified macro definitions are fetched from the 
Library in the order that they are found. If a macro definition 
cited in the MCALL instruction is not found in any library, the 
request for that definition is ignored. All libraries named in 
the MLIBS instruction are searched for the cited macro 
definitions. The MCALL instruction statement cannot occur within 
a Macro definition. 
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oem ow ao de oe oe 


{| MCOPY | 


5.1 


e3 Macro Copy (MCOPY) Statement 


The MCOPY statement ae source text to be copied from a 


specified logical u 


it (lu) or file descriptor at any point in a 


J 


macro definition or program. The copied source text can be any 
arbitrary text, such as a: 


set of global variables used in several macros, 


complete macro definition or a set of macro definitions, 


Part of a macro definiticn, 
set of equates, or 


subroutine. 


Copying starts at a specified point or at the beginning of the 
file. Copying terminates when: 


e a /* in columns 1 and 2 is encountered, 


@e an END statement is encountered, or 


An 


an end of file (EOF) is reached. 


END statement, if used as a terminator for MCOPY, will also 


terminate macro expansion. 


The syntax of the MCOPY statement is: 


ignored MCOPY, {label] {,lu number] 
{,file descriptor] 


where: 


If a label is not: specified, the file is not rewound and 
everything is copied until a /* in columns 1 and 2 or an EOF 
is reached. 


If a label is specified, search the file from its present 
position until a label cf the following form is found: 


** LABEL 
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If an EOF is encountered, the file is first rewound and 
searched once more for the label. If found, copying starts 
from the next statement until the next terminator is 
encountered. 


If the file is omitted, copying is performed from the current 
file, where the current file is initially lu 7. It can be 
-Changed with a START option, or the file or lu from the most 
recent preceding MCOPY statement at the same level. 


MCOPY statements can be nested up to 16 levels, provided 
sufficient logical units are available. For example: an MCOPY 
can copy a macro definition containing an MCOPY statement to copy 
global variables. The first MCOPY statement copies the initial 
part of the macro definition until the nested MCOPY statement is 
encountered. Then, the first MCOPY statement resumes. While the 
inner MCOPY statement is corying, two logical units are open. 


Operands of MCOPY passed to the macro processor through the MCOPY 
Start options are passed to each program in the batch. 
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5.1-4 Macro Definitions CMCDEFS) Instruction 


The MDEFS instruction controls which macro statements are sent to 
the CAL file. Its format is: 


NAME OPERATION OPERANDS 
blank MDEFS ohe or more codes 


separated by commas 


The optional letter N preceding the code means to suppress 
sending the statement; whereas, the code enables sending. The 
codes and their meanings are: 


5; MINIMUM 

CODE : MEANING ABBREVIATION 
(N)DEFS (NO) macro definitions . D ND 

(N) INNER (NO) inner macro calls I NI 

(N) OUTER (NO) outer macro calls Oo NO 

ALL send all of the above ALL 

NONE send none of the above NONE 

Example: 


MDEFS NI,ND 


suppresses macro definitions and inner macro calls to be sent 
to CAL. MDEFS can be specified as a START option. If 
specified as a START option, the MDEFS statement has no 
effect. MLDEFS cannot occur in a macro definition. Section 
6.2 details START options. 
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5.1.5 Macro Libraries (MLIBS) Instruction 


The MLIBS instruction designates the file descriptor or decimal 
lu numbers where the macro libraries, necessary for a given macro 
processor source stream, reside. The format of the MLIBS 
instruction is: 


NAME OPERATION OPERAND 


blank MLIBS one or more file 
descriptors or lu 
numbers separated 
by commas 


If any macro libraries (including the system macro library) are 
used, this statement must appear as a START option or in the 
Macro processor source stream prior to invoking any macros 
residing on a library. The operand field must contain at least 
one argument. The libraries are searched in the order that their 
file descriptor or lu numbers appear in the START option or MLIBS 
instruction. The absence of a START option or MLIBS' instruction 
in a processor source stream indicates to the processor that all 
required macro definitions for that saurce stream exist as part 
of the source stream. The maximum number of file descriptors or 
logical units that can be actively designated as libraries at any 
one time is 15. The MLIBS instruction statement cannot occur 
within a macro definition. See Section 6.2 for START options. 


The files and logical units passed to the macro processor through 
the MLIBS start options are passed to each program in the batch. 
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| MLIST | 


5.1.6 Macro Listing (MLIST) Instruction 


The MLIST instruction controls which macro statements are sent to 
the list device. Its format is: 


NAME OPERATION OPERAND 


blank MLIST one or more codes 
separated by commas 


The optional letter N preceding the code means to suppress 
sending the statements; whereas, the code enables sending the 
statement. The codes and their meanings are: 


. MINIMUM 
CODE MEANING ABBREVIATIONS 
(N) DEFS (NO) macro definitions D ND 
(N) INNER (NO) inner macro calls I NI 
(N) OUTER (NO) outer macro calls f) NO 
(N) CAL (NO) CAL code E NC 
(N) GENCAL (NO) generated code G NG 
(N) MNOTE (NO) MNOTE M NM 
ALL send all ALL 
NONE send NONE NONE 

Example: 


MLIST ND,NI 


suppresses macro definitions and inner macro calls to be sent 
to the list device. MLIST can be specified as a START 
option. If it is specified as a START option, the MLIST 
statement has no effect. MLIST cannot occur in a macro 
definition. | 
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| MPAUS | 
5.1.7 Pause (MPAUS) Instruction 
The MPAUS instruction permits the user to pause the macro 
processor. The pause can occur anywhere in the input stream; 


but, it cannot occur between a macro statement and a following 
macro prototype. An example of the MPAUS instruction is: 


NAME OPERATION OPERAND 


blank MPAUS blank 
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| MTRAC | 


5.1.8 Macro Trace (MTRAC) Instruction 


The diagnostic instruction, MTRAC, determines the effective 
conditional branches and the SET variable symbols values within 
the macro logic. The format of the MTRAC instruction is: 


NAME OPERATION OPERAND 


blank MTRAC blank 


The MTRAC instruction can occur anywhere in the source’ stream. 
It causes the macro trace feature to be enabled for all 
subsequent macro instructions processed. Each time a macro is 
invoked, a map of its expansion, detailing the path of the 
conditional branches :and the values of the SET variable symbols, 
is written to the designated trace output device (lu 3). If the 
MTRAC statement occurs within a macro definition, the trace 
feature is enabled every time the corresponding macro is invoked 
and remains enabled until a no trace (NTRAC) statement is 
encountered in a macro definition expansion or in the source 
stream. 
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5.1.9 No Libraries (NOLIB) Instruction 


The NOLIB instruction suppresses searching all or some macro 
libraries previously designated by the MLIBS statement. The lu 
numbers of the libraries that searching is to be suppressed for 
are contained in the NOLIB statement operand field. If the 
operand field is blank, all library searching is suppressed. The 
format of the NOLIB instruction is: 


NAME OPERATION OPERAND 

blank NOLIB one or more file descriptors 
or lu numbers separated by 
commas 


The NOLIB instruction is useful in these situations: 


@ If memory size is such that all macro definitions invoked in 
a given processor source stream can be made memory resident at 
the same time: 


- the MCALL instructicn brings all the macro definitions into 
memory prior to their use: then, 


- the NOLIB instructicn is invoked with a blank operand 
field, causing all library searches to be suppressed. 


If erroneous operation ccdes are present in source statements, 
the NOLIB instruction prevents unnecessary library searches. 


e Tf memory size is not sufficient to allow all macro 
definitions necessary for a given processor pass to be made 
‘Memory residents: : 


- the MCALL instruction brings aS many macro definitions as 
possible into memory; (ideally, these include the most 
frequently used macro definitions); then, 


- the NOLIB instructicn is invoked to suppress searching the 
libraries from which the memory-resident macro definitions 
were extracted. 


This technique minimizes the necesSary processing time for 
library searches ina limited memory environment. The NOLIB 
instruction statement cannot occur within a macro definition. 
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5.1.10 No Trace C(NTRAC) Instruction 


The NTRAC instruction causes the macro trace feature to be 
disabled. If NTRAC occurs in a macro definition, the macro trace 
feature is disabled each time that macro is invoked. 


NAME | CPERATICN OPERAND 


blank NTRAC blank 
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CHAPTER 6 
OPERATION OF THE CAL MACRO/32 PROCESSOR 


6-1 INTRODUCTION 

This chapter demonstrates the operation of the CAL Macro/32 
Processor (MACRO) and 0S/32. 

The CAL Macro Processor is available as a 32-bit object program. 


6.1.1 Device Assignments 


The CAL Macro Processor uses these device assignments: 


AS LU 1 Source input 
AS LU 2 Expanded source output 
AS LU 3 Listing, trace output, and error messages 


(see Appendix D) 


Any other available logical unit (lu) can be used for libraries. 


6-1-2 Memory Requirements 
The macro processor requires approximately 26kb of memory over 
and above what the operating system uses and the macro processor 


itself requires for any table space. The macro processor 
requires table space for stcring: 


@® programmer macros, 
e library macros defined by an MCALL statement, 

e global symbols, and 

@® any parameters associated with the macro instruction currently 


being processed. 


Thus, the amount of table space required depends on the program 
being processed. 
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6.2 OPERATION OF THE MACRO PROCESSOR UNDER 0S/32 

Prior to using the macro rrocessor, it must be established as a 
user task with OS/32 Link. Refer to the OS/32 Operator Reference 
Manual and the OS/32:' Link Reference Manual. 


Once the macro processor is established, it is loaded by 0S/32 
with the command: 
LOAD taskid,fd 


where: 


taskid is the name assigned to the macro processor task 
partition. 


fd is the file descrirtor or device mnemonic containing the 


established macro processor. 


The macro processor task is made the currently selected task for 
Making device assignments, starting with the command: 


TASK taskid 


Assign all logical units that the macro processor is to use: 


LU | COMMAND DEVICE 

source input ‘AS 1,SOURCE.MAC disc 

list output |AS 3,PR: printer 
source output iAS 2,SCURCE.CAL disc 

macro library* ‘AS 7,MAG1: Magnetic tape 


*The macro library is not a required assignment; 
when used, it can be assigned to any available 
LU number. 


Issue the operating system START command to execute the macro 
processor: 


START 


The macro processor then executes. When the entire source 
program has been processed, the macro processor issues an SVC 3, 
end of task code 0 to the operating system if no errors are 
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detected. The following end of task codes may be returned by the 
macro processor: 


: No errors 
: Errors in macro expansion 
: Invalid start option 

54: Insufficient memory 


Of N oO 


Any other return code is due to an MNOTE statement in the listing 
which set the return code. 
6-3 I/0 ERRORS 
When the macro processor detects an I/0 error during its 
operation, it prints this message on the system console: 
I/O ERROR xxdd 
wheres: 
xx is a 2-digit hexadecimal value representing the device 
status. 
dd is the device number causing the error. 


The possible values of xx are: 


DEVICE 
STATUS 
CODE MEANING 
CoO illegal functicn 
AO device unavailable 
90 end of medium 
88 end of file 
84 unrecoverable error 
82 parity/recoverable error 
8 1 unassigned lu 


Examples: 


9085 end of medium on magnetic tape 
AO0O4 card reader offline 
C062 READ attempted from the line printer 


Refer to the appropriate operating system manual for details 
on the status of each device. 
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6.4 START OPTIONS 


START options are provided for these functions: 


FUNCTION 


MLIST 
MDEFS 
MLIBS 


MCOPY 
NTRAC 
BATCH 


When invalid 
which option 


START OPTION 


(option, option,...eoption) 

(option, option,.e.-eoption) 

(fd or lu number) 

the order specifies the search order 

fd or lu number 

globally turns off all trace facilities 
batch mode 


start options are specified, a message indicating 
is in error is logged to the user console. The task 


is terminated with an end of task code 4. 


Examples: 


START 
START 
START 


/MLIBS=(8,9,10) 
,MCOPY=7,B,NTRAC 
¢NTRAC, MLIST=(NONE,GEN) 


6.5 CAL MACRO/32 PROCESSCR TERMINATION 


The CAL Macro Processor goes to end of task under the following 


conditions: 


- An END 


statement is encountered outside the scope of ASIS, 


and BATCH is not specified in the start option or in line. 


- An end 
which 
in the 


- A BEND 


- An end 
(which 


of file is encountered following an END statement 
is in the scope of ASIS, and BATCH is not specified 
start option or in line. 


etatement is encountered. 


of file is encountered following an END statement 
is generated or in the scope of ASIS), and BATCH is 


specified in the start option or in line. 
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CHAPTER 7 
MACRO LIBRARY UTILITY PROGRAM 


721 INTRODUCTION 

The Perkin-Elmer Macro Library Utility Program (03-340) provides 
the capabilities for establishing and maintaining the system 
Macro library and/or any user designated macro libraries. It 
can: 

@e create a new library (ESTABLISH command), 


e maintain an existing library (GET command), 


@e include new macro definitions into a library CINCLUDE 
command), 


e delete macro definitions from a library (DELETE command), 


e list macro definitions from a library to a device file (LIST 
command), 


e print the directory (names of the macros) of a library to a 
device or file (DIRECTCRY command), 


e save an updated library to a permanent file (SAVE command), 


e facilitate magnetic tape positioning (FF, BF, RW, WEM 
commands), and 


@e accept comment statements (*). 


7-2 MACRO LIBRARY 


A macro library is a 256-LEyte record file with this format: 


e Header record 
e Index records 


e Macro definitions 
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7.2.1 Header Record 
The header record, the first record in any macro library, 


contains information on the last date the library was modified, 
the size of the library, the type of medium, and user comments. 


The header record has this format: 


BYTES | DESCRIPTION 
1-8 date library was last modified 
9 medium code "D" (disc) “M" (magnetic tape 


or tape cassette) 


10 blank 

11-12 last record of the current library 
13-80 comments or blanks 

81-256 blanks 


The ESTABLISH command creates the header record or the GET 
command retrieves it from an existing library. 


7e2e2 Index Records 


Index records follow the header record. Index records locate 
macro definitions within a library. The number of index records 
depends on the number of macro definitions in the library. The 
macro library utility adjusts the number of records as 


definitions are INCLUDEd cr DELETEd. Each index record contains 
from 0O to 21 entries.| The last entry is marked with an internal 
end-of-block mark. The format of each entry is: 


BYTES DESCRIPTION 

1-8 macro name - the one to eight character 
mnemonic hame used when the macro is 
invoked. 

9-10 zero 

11-12 relative record number of the macro 
definitions 


7=2 48-057 FOO ROO 


7e2e3 Macro Definitions 


Each macro definition starts on a 256-byte record boundary. The 
definition records are packed into a variable number of variable 
length logical records (81 bytes maximum). A carriage return 
(CR) designates the end of a logical record. To facilitate 
packing, Single blanks rerlace the logical records having leading 
and trailing blanks. No logical record is split between two 
physical records. The records are ASCII. 


7-3 COMMAND FORMAT 


Each macro library utility command has this format: 
command arg1,arg2,e<«-ceargn 


The command verb begins in the first nonblank space of a line and 
specifies the operation to be performed. The arguments modify 
the command. The command verb can be specified as the entire 
verb or any sequence of leading characters making the verb 
unique. 


Example: 


DE 

DEL 

DELE 

DELET 

DELETE 
All of these verb forms can be accepted for DELETE. The verb 
form DEM is not accepted for DELETE. 
The arguments are separated from the command by at least one 
blank and from each other by commas or blanks. To obtain the 
default value if a required argument is omitted, the comma must 
be included. An end-of-record indicator or 80 bytes, whichever 
comes first, terminates the command line. 
If multiple lines are needed for a command, the last nonblank 
character of the line to be continued must be a comma. The 


arguments continue on the next nonblank character of subsequent 
lines. 
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Example: 


command arg1,arg2, 


argi,.e.-,argj, 
arg) ~.as vargn 


7-4 MACRO LIBRARY UTILITY COMMANDS 


The standard format for the user-~specified file descriptor (fd) 


is: 


{zr eomeed oa 


voln: or 


filename 


ext 


11 a rd 


dev: 


is a disc volume or device name from one to 
four characters long. 


is a filename from 1 to 8 characters long. 


is the extension name and is from one to three 
characters long preceded by a period. 


are Single alphabetic characters representing 
the file class. They are: 


P private file 
G grour file 
S system file 


The following sections detail each macro library utility command. 


7-4 
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7-4-1 BF Command 


The BF command backspaces a magnetic tape device. The device is 
assigned. The number of specified filemarks are repositioned and 
closed. 


Format: 
BF file descriptor, [decimal number| 


Parameters: 


file is the file descriptor of the device to be 
descriptor backspaced. 

decimal is the number of filemarks to be backspaced. 
number If the number of filemarks to be backspaced is 


not specified, the default is 1. 


Programming Considerations: 


Ensure that filemarks are on the tape. Do not attempt to 
backspace a magnetic tape that daes not have a beginning 
filemark. 


Error Messages: 


NO FILE Indicates that the file descriptor of the 
DESCRIPTCR device to be backspaced was not specified. 
SPECIFIED 
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724.2 DELETE Command 


The DELETE command deletes macro definitions from a 
library. 
Format: 

DELETE macro,eee 
Parameters: 

macro is the one to eight character name of 

MaCrlOe 
Programming Considerations: 
The requested macros are deleted from the macro library. 
updated library taskid.001 is assigned; the message: 

UPDATED TEMPORARY LIBRARY VOL:taskid.001 NOW AVAILABLE 
appears. This library can be further modified. When 
modifications have been completed, use the SAVE command. 
Error Messages: 

NO LIBRARY Indicates that a macro library is not pre 

PRESENT Use the ESTABLISH or GET commands. ~ 

MACRONAME Indicates that the macroname was not foun 

NOT FOUND 


macro 


the 


An 


all 


sent. 


de 
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7-423 DIRECTORY Command 


The DIRECTORY command writes the | names’ of 


library to an output device. 
Format: 

DIRECTORY [file descriptor] 
Parameters: 


file 
descriptor 


is the file or device 
Macros are written. 
not specified, the 
console. 


W 
If 
de 


Programming Considerations: 


The date the library was last modified and 
header are also written. The index blocks 
names. If the file descriptor does not 
and assigned. If the file descriptor does 
is written to the end-of-file. The file i 
the DIRECTORY command. 
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DIRECTORY 


all macros in the 


here the names of all 
the file or device is 
fault is the system 


the comments from the 
are searched for macro 
exist, it is allocated 
exist, the directory 
s closed at the end of 


7-4.4 END Command 


The END command normally terminates the macro library utility. 
Format: 

END 
Programming VORPSReret Tenn! 


If the temporary library task-id.001 Was not saved, this 
information message: ! 


REMINDER! SAVE YOUR CURRENT LIBRARY 


is issued. A second END command deletes that file and goes to 
end of task. If changes were not made to a library, a normal end 
of task is taken. 
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| ESTABLISH | 


7-4.5 ESTABLISH Command 


The ESTABLISH command creates a hew macro library. 


Format: 


ESTABLISH file descrirtor ,comments 


Parameters: 


file is the filename or device of the new macro 
descriptor library.e 
comments represents up to 63 characters of user 


comments. 
Programming Considerations: 


If the temporary library task-id.001 was not’ saved, this 
information message: 


REMINDER! SAVE YOUR CURRENT LIBRARY 


is issued once. A second ESTABLISH, GET, or END command is 
performed. If changes to a previous library were not made, a new 
library is created and the frevious unchanged library is closed. 


Error Messages: 


INSUFFICIENT Not enough memory space exists for this 
MEMORY FCR library. 
THIS LIBRARY 
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724.6 FF Command 


The FF command spaces a magnetic tape forward to a filemark. 


Formats: 
FF file descriptor [,decimal number | 


Parameters: 


file is the device to be repositioned. 

descriptor 

decimal is the number of filemarks. If the number 

number of filemarks is not specified, the default is 
one. 


Programming Considerations: 


The device is assigned, repositioned (the number of filemarks), 
and closed. 


Error Messages: 


NO FILE A file descriptor was not specified. 
DESCRIPTOR 
SPECIFIEL 
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7e4.7 GET Command 


The GET command obtains an existing macro library for updating. 
Formats 

GET file descriptor 
Parameters: 


file is the existing macro library. 
descriptor 


Programming Considerations: 


If the temporary library task-id.001 is present, the information 
message: 


REMINDER! SAVE YOUR CURRENT LIBRARY 


is issued once. A second GET, ESTABLISH, or END command is 
performed. If changes were not made to a previous library, the 
new library is obtained and the previous unchanged library is 
closed. 


Error Messages: 


NO FILE A fie descriptor was not specified. 
DESCRIPTOR 
SPECIFIED 

LU 1 file descriptor DOES NOT EXIST--CANNOT ASSIGN 

RECCRD LENGTH NOT 256. NOT A MACRO LIBRARY. 
INSUFFICIENT Not enough memory space for this library. 


MEMORY FOR 
THIS LIBRARY 
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704.8 INCLUDE Command 

The INCLUDE command includes new macro definitions into a 
library. 

Format: 


INCLUDE file descripter [-macro] [,macro]... 


Parameters: 


file is the source filename. 
descriptor 
macro is the one to eight character macro name. If 


the character macro name is not specified, the 
default is all macros on the source file. 


Programming Considerations: 


The macro(s) specified (all if none specified) are included in 
the current macro library. The old library is closed and the 
updated temporary library task-id.001 is assigned as the current 
library; and, the messages: 


XXX MACROS INCLUDED FROM file descriptor 
UPDATED TEMPORARY LIBRARY VOL: task-id.001 NOW AVAILABLE 


are issued. This library must be saved to become permanent. 
Macro definitions to be included in a library must be reasonably 
debugged and syntactically correct. A minimum of error checking 
is performed on the macro statementse An invalid CAL statement 
could cause problems and should be avoided. Any file that CAL 
Macro can process with NO ERRORS can be used safely as input to 
the macro library utility. Macros should be tested with CAL 
Macro before they are placed ina library. 


A single blank replaces leading and trailing blanks to conserve 
library space and provide for a faster running of CAL Macro. 
Macro definitions with sequence numbers, while accepted, should 
be used since blank compression cannot be performed. 
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Error Messages: 


NO FILE DESCRIPTOR SPECIFIEL 


DUPLICATE MACRO macroname The macro already exists in the 
library. 


ILLEGAL MACRO NAME name The macro prototype statement is 
invalid. 


The following statements inside a macro definition cause an 
error: 


MACRC STATEMENT ENCOUNTERED AT LINE XXX - Macro 
MEND STATEMENT ENCOUNTERED AT LINE XXX - Mend 
BEND STATEMENT ENCOUNTEREL AT LINE XXX - Bend 
END STATEMENT ENCOUNTERED AT LINE XXX - End 


EOF ENCOUNTERED IN A MACRO CEFINITION 


The assumption is that there is a missing MACRO or MEND 
statement. If any of these messages occur, check the library 
carefully to find which macros have actually been included. 
Also, column 72 of the statement preceding the MEND must be 
blank. A statement that extends past column 72 causes the MEND 
statement to be treated as a continuation. However, an END 
Statement in the range of an ASIS statement does not cause _ the 
error, nor does it terminate the INCLUDE command. 
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72.4.9 LIST Command 


The LIST command writes macro definitions to an output device. 
Format: 

List [file descriptor][,macro],... 
Parameters: 


file the file Or device where the macro 

descriptor definitions are written. If a file or a 
device is not specified, the default is the 
system console. 


macro Mames cf the macros to be written. If the 


Names are not specified, the default is all 
macros in the library. 


Programming Considerations: 

Macro definitions are written to the output device in the order 
that the LIST command specifies. If the file does not exit, it 
is allocated and assigned. If the file does exit, the macro 
definitions are written to the end of the file. The file is 
closed at the end of the LIST command and one of these messages 
is written: 

n MACROS LISTED TO file descriptor 


or 


| 
n MACROS LISTED TO NEW FILE file descriptor 


Error Messages: 


NO LIBRARY PRESENT no macro library is present (use the 
GET or ESTABLISH commands). 


name MACRO NOT FOUND a macro was not in the library 


THIS LIBRARY CONTAINS the library has to be rebuilt 
INVALID MACROS 
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724.10 PAUSE Command 


The pause command pauses the macro library utility. 
Format: 


PAUSE 
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724.11 RW Command 
This command rewinds a magnetic tape. The device is assigned and 
closed. 
Format: 
RW file descriptor 


Parameters: 


file is the device name of the magnetic tape to 
descriptor be rewound. 


Error Messages: 


NC FILE DESCRIPTOR SPECIFIED 
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7Te4.12 SAVE Command 
The SAVE command saves the temporary updated macro library to a 


permanent file or device. 


Formats: 


file descriptor 
SAVE 


* 


Parameters: 


file is the name of a new file. 


descriptor 
* is the same file descriptor used in the last 


GET or SAVE command. 
Programming Considerations: 


The SAVE file descriptor causes a new file descriptor to be 
allocated and assigned. If the file already exists, this message 
appearss 


file descriptor EXISTS. DELETE AND REALLOCATE? 
Expected responses are: 

YES or NO 
Any other response issues the message: 

PLEASE ANSWER YES OR NO 


A NO response does nothing more and invites the next command. A 
YES response first deletes the old library. If the old library 
Was a private disc file, the temporary library task-id.001 is 
then renamed to the old library. If a rename is not possible 
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(different disc, magnetic tape), then the temporary library 
task-id.001 is copied to the new file or device. In either case, 
the new library is assigned as the current library. 

If SAVE * is issued, | this action occurs without the prompt 
message. SAVE * should not be issued for a file that cannot be 


renamed or ailocated (system or group file or magnetic tape). 


If the SAVE is successful, the message: 
UPDATED LIBRARY file descriptor NOW AVAILABLE is written. 
Errer Messages: 


NO FILE DESCRIPTOR SPECIFIED 
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724.13 WEM Command 


The WFM command writes a filemark to a magnetic tape. 
FORMAT: 

WFM file descriptor 
Parameters: 


file is the device to write a filemark. 
descriptor 


Programming Considerations: 


The device is assigned; a filemark is written; and the device is 
closed. No further repositioning occurs. The magnetic tape is 
then positioned after the filemark. 


Error Messages: 


NO FILE DESCRIPTOR SPECIFIED 
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724.14 Comments 
Any character string starting with an asterisk (*) in column 1 is 


treated as a comment. 


Formats 


* any string of characters 
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7.5 OPERATION WITH A MACRO LIBRARY ON MAGNETIC TAPE 


The positioning and automatic repositioning of a magnetic tape by 
the macro library utility are important if the library resides on 
Magnetic tape. This list shows positioning before and after each 
commands: 


COMMAND BEFORE | AFTER 
GET Beginning of header Beginning of first macro 
record or library (first record 


after index records) 


COPY Beginning of first Same 
macro or library 

INCLUDE Reginning of first Past filemark at end of 
macro or library library 

DELETE Beginning of first Past filemark at end of 
macro or library library 

SAVE Assumption Beginning of first macro 
(see other commands) new library (same as 


GET) beginning and ending 
file marks automatically 
written 


DIRECTORY No change No change 


7-6 OPERATION OF A MACRO LIBRARY UTILITY UNDER OS/32 

Before the macro library utility can be used, it must be 
established as a user task with OS/32 Link. See the 0S/32 
Operator Reference Manual and the OS/32 Link Reference Manual. 

An EXPAND factor should be included in Link. To process’ the 


command, 256 bytes are needed and an additional 256 bytes are 
needed for every 21 macros ina library. 


Example: 


EXPAND 6 is sufficient to process 100 macros. 


Once the macro library utility is established, it is loaded by 
the operating system with the command: 


LOAD taskid,fd 
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wheres 


taskid is the name assigned to the macro library 
utility partition. 


fd is the file descriptor or device mnemonic 
containing the established macro library 
utility. 


The macro library utility task is made the currently selected 
task with the command: 


TASK taskid 


Device assignments do not have to be made. However, if a device 
other than CON: is to be used for command input and message 
output, the input and output can be assigned to LU 5 and LU 6, 
respectively. 


The macro library utility is executed with the command: 


START 


If the files taskid.001, taskid.002, or taskid.003 exist, they 
must be renamed or deleted. These files are used as scratch 
files for the macro library utility. 
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APPENDIX A 
COMMAND SUMMARY 


BF file descriptor, [decimal number| 


backspaces a magnetic tape to a filemark. 


DELETE macro,eee 


deletes macro definitions from a macro library. 


DIRECTORY [file descriptor] 


writes the names of all macros in the library to an 
device. 


END 


normally terminates the macro library. 


ESTABLISH file descriptor ,comments 


creates a new macro library 


FF file descriptor [-decimal number | 


forward spaces a magnetic tape to a filemark. 


GET file descriptor 


obtains an existing macro library for updating. 


INCLUDE file descriptor [,macro|[,macro]... 


includes new definitions into a library 


List [file descriptor] |,macro],... 


writes macro definiticns to an output device 
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output 


PAUSE 


pauses the Macro Library Utility 


RW file descriptor 


rewinds a magnetic tare 


file descriptor 
SAVE 


* 


Saves the temporary updated macro library to a permanent file 
or device 


WFM file descriptor 


writes a filemark to a magnetic tape 


A-2 48-057 FOO ROO 


OPERATICN 


APPENDIX B 
INSTRUCTION STATEMENT SUMMARY 


OPERAND 


symbol 


symbol 


sequence 
symbol 


symbol 


sequence 
symbol 


sequence 
symbol 
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ACTR 


AGO 


ANOP 


ASIS 


BGBLA, 
BGBLC 


GBLA, 
GBLC 


LCLA, 
LCLC 


MACRO 


MEND 


MCALL 


MDEFS 


MEXIT 


BGBLB, 


GBLB, 


LCLB, 


Logical expression enclosed 
in parentheses immediately 
followed by a Sequence symbol 


Any expression that can appear 
in the operand field of a SETA 
instruction 


A sequence symbol 


Blank 


Blank, decimal integer, 
BEGIN, or END 


One or more variable symbols 
used as batch global SET 
variable symbols, separated by 
commas 


One or more variable symbols 
used as global set variable 
symbols, separated by commas 


One Or more variable symbols 
used as local SET variable 
symbols, separated by commas 


Version number and date or any 


other optional description. 
Column 72 is blank. 


MACRO, MACRO,+«++, MACRO 


One or more codes separated by 
commas 


ee ee ee een 


| { 
OPERATICN | 


sequence 
symbol 


SETA 


symbol or 
array 
element 


SETB 
symbol or 
array 
element 


SETC 
symbol or 
array 
element 


ee T_T FL Oe eee 


MLIST 


MNOTE 


MPAUS 


MTRAC 


NCLIB 


NTRAC 


SETA 


SETC 


ee ee eee ee oon ee eee SE eee re eee cere Gee cies come Seem qe Owens cee eee ee oe eee seem eee eee EE eee, come See oneee see CMe ee Ce ee oo 


OPERAND 
One or more file descriptors 
or lu numbers separated by 
commas 


One or more codes separated 
by commas 


An optional integer expression 
followed by a quoted message 
string separated by a comma 


One or more file descriptors 
or lu numbers separated by 
commas 


An arithmetic expression 


O, 1, or logical expression 
enclosed in parentheses 


One operand consisting of a 
type attribute, character 
expression, substring nota- 
tion or concatenation, or sub- 
string notations and character 
expressions 
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APPENDIX C 
EXAMPLES OF MACRO EXPANSION 


Example 13 Expansion of the Macro Instruction COMPR 


The following example shows the expansion of the macro 
instruction, COMPR. COMPR compares two byte-oriented fields 
(ZFLD1 and #FLD2) of equal length (%SIZE) for a normal condition 
(ZPEQe-NE) of equal or nonequal.e. If the normal condition is not 
met, a branch is taken to an error routine (%ERRTN). 


The expansion of the COMPR macro instruction is subject to this 
restriction: 


The operand replacing the symbolic parameter %EQ.NE must not 
be "EQS or ‘NE*. 


If this restriction is not met, further macro expansion is 
suppressed and the appropriate error message is passed to the 
source stream. 


MACRO 1 
ANAME COMPR AFLD1,%FLD2,4SIZE,AZEQeNE,AERRIN 2 
GBLB ’BG01,%BG02 3 
AIF . ((*ZEQ.NE* NE *EQ') AND (*REQ.NE* NE ‘NE*))&ERR1 4 
STM 11,d00RHOLD SAVE REGS 11 THRU 15 5 
AIF (*AEQ.NE* EQ °EQ*)&EQO1 6 
BAL 12, 000CMPNE GO CHECK FOR NOT EQUAL. 7 
AGO ESETARGS 8 
&EQ01 ANOP 9 
BAL 12,000CMPEQ GO CHECK FOR EQUAL. 10 
&SETARGS ANOP 11 
DAC ACRFLD1) BASE ADDRESS OF FIELD 1. 12 
DAC ACAFLD2) BASE ADDRESS OF FIELD 2. 13 
DAC ASIZE FIELD SIZE FOR COMPARE. 14 
DAC A (ZERRTN) ADDRESS OF ERROR ROUTINE. 15 
AIF (*REQ.NE® EQ ‘EQ*)&EQO2 16 
AIF (%ZBG01 EQ 1)&GETOUT 17 
AIF (%BGO02 EQ 1)&SHORT 18 
B 6*ADC+adORHOLD BYPASS COMPARE SUBROUTINE 19 
AGO ECMPNE 20 
&SHORT ANOP 21 
B @OONEOO1+4 BYPASS COMPARE SUBROUTINE 22 
ECMPNE ANOP 23 
@Q2aCMPNE AIS 12,ADC-2 ASSURE CORRECT ALIGNMENT OF 24 
AGO &SUBR 25 
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&EQ02 


&SHORT1 
&CMPEQ 


@aACMPEQ 
&SUBR 


ANAME 


ANAMESA 


ANAME:B 


@daNEO01 
”%BGO1 


@dMRHOLD 


&EQ03 


ANAME:B 


@aaEQ001 
ABGO2 


®@2ORHOLD 


&ERR1 


EGETOUT 


CMPREQ1 


SETB 
AIF 
DAS 
MEXIT 
ANOP 
MNOTE 
MEXIT 
ANOP 
MEND 


COMPR 
STM 
BAL 


26 
(ABGO2 EQ 1)&GETOUT 27 
(%BGO01 EQ 1)&SHORT1 ; 28 
6*ADC+da aMRHOLD BYPASS COMPARE SUBROUTINE. 29 
ECMPEQ ~ 30 
31 
@OdEQO01+4 BYPASS COMPARE SUBROUTINE. 32 
33 
12, ADC-2 ASSURE CORRECT ALIGNMENT OF 34 
35 
12,-ADC ADDRESS OF ARGUMENT LIST. 36 
15,0(12) R15=ADDR OF 1ST FIELD. 37 
14,ADC(12) R14=ADDR OF 2ND FIELD. 38 
13,2*ADC(12) R13=FIELD SIZE. 39 
11,3*ADC(12) R11=ADDR OF ERROR ROUTINE. 40 
12,4*ADC POINT R12 TO RETURN ADDR. 44 
12,5*ADC+@@a@RHCLD SAVE RETURN ADDR. 42 
12,0(15) R12=BYTE FROM FIELD 1. 43 
12,0(174) COMPARE WITH SAME BYTE 
IN FIELD 2. 44 
ANAME:B GET OUT IF THEY'RE NOT EQUAL. 45 
15,1 BUMP ADDR OF FIELD 1. 46 
14,1 BUMP ADDR OF FIELD 2. 47 
13,1 DECREMENT FIELD SIZE. . 48 
ANAME CHECK NEXT BYTE IF 
FIELD SIZE > 0 49 
("REQ.NE® EQ *EQ')E&EQO3 50 
12,ADC+@@aRHOLD FIELDS ARE =, 
RESTORE REGS & ERROR 51 
0(¢11) EXIT. 52 
11,5*ADC+a@ddRHOLD FIELDS ARE NOT =, 
R11 - NORMAL RETURN 53 
ANAMESA GO RESTORE REGS AND GET OUT 54 
1 55 
(ABGO2 EQ 1)&GETOUT 56 
6 REGISTER & RETURN SAVE AREA 57 
58 
59 
11,5*ADC+0d@RHCLD FIELDS ARE =, 
R14 = NORMAL RETURN 60 
12, ADC+ddadRHOLT RESTORE REGS (ALSO HERE 
IF FLDS NOT =) 61 
0(11) EXIT. 62 
1 63 
(%BGO1 EQ 1)&GETOUT 64 
6 REGISTER & RETURN SAVE AREA 65 
66 
67 
‘INVALID COMPARE TYPE‘ 68 
69 
70 
71 
FLDA,FLDB,26,EQ,ERROR1 72 


11,2@@RHOLD 
12,200CMPEQ 


SAVE REGS 11 THRU 15. 
GO CHECK FOR EQUAL. 
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®OACMPEQ 


CMPREQ1 


CMPREQ1B 
@2dEQ001 
@dORHOLD 
CMPRENE1 


@OOCMPNE 


CMPRNE1 


CMPRNE1A 


CMPRNE1B 
@2ANEOO'1 
CMPREQ2 
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A(FLDA) 

A(FLDB) 

26 

A(ERROR1 ) 
6*ADC+dd0@RHOLD 
12,ADC-2 
12,-ADC 
15,0(12) 
14,ADC(12) 
13,2*ADC(12) 
11,3*ADC(12) 
12,4*ADC 
12,5*ADC+adadRHCLD 
12,0(15) 
12,0(14) 
CMPREQ1B 

15,1 

14,1 

13,1 

CMPREQ1 
11,5*ADC+ddaRHOLD 
12, ADC+@dadaRHOLD 
0(11) 

6 


AFLD, BFLD,91,NE,ERRO1 


11,a@aaRHOLD 
12,9aaCMPNE 
ACAFLD) 

A(BFLD) 

91 

A(ERRO1) 
@aaNEO01+4 
12,ADC-2 
12,-ADC 
15,0(12) 
14,ADC(12) 
13,2*ADC(12) 
11, 3*ADC(12) 
12,4*ADC 
12,5*ADC+@daRHOLD 
12,0(15) 
12,0(14) 
CMPRNE1B 

15,1 

14,1 

13,1 

CMPRNE1 

12, ADC+aaaRHCLE 
0(11) 
11,5*ADC+9aaRHOLD 
CMPRNE1A 
F1,F2,13,EQ,ERROR2 
11,dddRHOLD 
12,ddaCMPEQ 
A(F1) 

ACF2) 


BASE ADDRESS OF FIELD 1. 

BASE ADDRESS OF FIELD 2. 

FIELD SIZE FOR COMPARE. 

ADDRESS OF ERROR ROUTINE. 

BYPASS COMPARE SUBROUTINE. 

ASSURE CORRECT ALIGNMENT OF 
ADDRESS OF ARGUMENT LIST. 

R15=ADDR OF 1ST FIELD. 

R14=ADDR OF 2ND FIELD. 

R13=FIELD SIZE. 

R11=ADDR OF ERROR ROUTINE 

POINT R12 TO RETURN ADDR. 

SAVE RETURN ADDR. 

R12=BYTE FROM FIELD 1. 

COMPARE WITH SAME BYTE IN FIELD 2. 
GET OUT IF THEY'RE NOT EQUAL. 

BUMP ADDR OF FIELD 1. 

BUMP ADDR OF FIELD 2. 

LECREMENT FIELD SIZE. 

CHECK NEXT BYTE IF FIELD SIZE > 0. 
FIELDS ARE =, R11 = NORMAL RETURN. 
RESTORE REGS (ALSO HERE IF FLDS NOT 
EXIT. 

REGISTER & RETURN SAVE AREA. 


SAVE REGS 11 THRU 15. 

GO CHECK FCR NOT EQUAL. 

BASE ADDRESS OF FIELD 1. 

BASE ADDRESS OF FIELD 2. 
FIELD SIZE FOR COMPARE. 
ADDRESS OF ERROR ROUTINE. 
BYPASS COMPARE SUBROUTINE. 
ASSURE CORRECT ALIGNMENT OF 
ADDRESS OF ARGUMENT LIST. 
R1S=ADDR OF 1ST FIELD. 
R14=ADDR OF 2ND FIELD. 
R13=FIELD SIZE. 
R14=ADDR OF ERROR ROUTINE. 
POINT R12 TO RETURN ADDR. 
SAVE RETURN ADDR. 

R12=BYTE FROM FIELD 1. 
COMPARE WITH SAME BYTE IN FIELD 2. 
GET OUT IF THEY'RE NOT EQUAL. 
BUMP ADDR OF FIELD 1. 

BUMP ADDR OF FIELD 2. 
DECREMENT FIELD SIZE. 

CHECK NEXT BYTE IF FIELD SIZE 0. 


FIELDS ARE =, RESTORE REGS AND ERROR. 


EXIT. 


73 


FIELDS ARE NOT =, R11 = NORMAL RETURN. 


GO RESTORE REGS & GET OUT. 


SAVE REGS 11 THRU 15.- 

GO CHECK FOR EQUAL. 

BASE ADDRESS OF FIELD 1. 
BASE ADDRESS OF FIELD 2. 


74 


DAC 13 | FIELD SIZE FOR COMPARE. 


DAC ACERROR2) ADDRESS OF ERROR ROUTINE. 
CMPRNE2 COMPR FLD1,FLD2,52,NE,ERRO2 75 
STM 11,@aaRHOLD SAVE REGS 11 THRU 15. 
BAL 12,00aCMPNE GO CHECK FOR NOT EQUAL. 
DAC AC(FLD1) BASE ADDRESS OF FIELD 1. 
DAC A(FLD2) BASE ADDRESS OF FIELD 2. 
DAC 52 FIELD SIZE FOR COMPARE. 
DAC A(ERRO2) ADDRESS OF ERROR ROUTINE. 
COMPARE COMPR FIELDA,FIELDB, 39,LT,ERRO3 76 
* MNOTE ‘INVALID COMPARE TYPE‘ 


SUMMARY: 


When the first equal compare (EQ) is made, the subroutine 
*dOODCMPEQ’ is expanded. When the first request for a nonequal 
compare (NE) is made, the subroutine ‘dadCMPNE* is expanded. All 
subsequent uses of the COMPR macro instruction in the same source 
stream result in the .expansion of a BAL to the applicable 
Subroutine, followed by an argument list. When the macro 
instruction CCMPR is first invoked (for an equal or a nonequal 
compare), a register storage area identified by the label 
*‘@@M@RHOLD' is defined. Registers 11 through 15 are used in 
executing the subroutines; but, registers 12 through 15 are 
restored before exiting. The original contents of register 11 
are available to the user in location dd2dRHOLD. 


ANALYSIS: 
e Statements 1 through 71 constitute the macro definition. 
e Statements 72 through 76 show 5 possible calls of the macro. 


e Statement 72 represents the initial call of the COMPR- macro 
instruction in the current source stream and the initial use 
of the EQ operand in a COMPR instruction in this source 
stream. This representation of the statement results in the 
full expansion of the daaCMPEQ subroutine and the register 
storage area ‘d@a@RHOLD' appended to the ‘ddadRHOLD' subroutine. 


When the a@@a@CMPEQ Subroutine is completed, the binary global 
"%BGO2' is set to true, indicating the presence of the 
subroutine. 

e Statement 73 represents the initial use of the NE operand in 
a COMPR instruction in this source stream, which results in 
the full expansion of the ddaCMPNE subroutine. The text of 
%BGO2 in statement 56 causes the definition of the register 
storage area to be suppressed and further macro expansion to 
be terminated. When the expansion of the daaCMPNE subroutine 
is completed, the ‘%8G01°' binary global is set to true, 
indicating the subroutine. 
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e Statement 74 represents a subsequent use of the EQ operand and 
results in the expansion of a BAL to @a@aCMPEOQ followed by the 
applicable argument list. 


e Statement 75 represents a subsequent use of the NE operand and 
results in the expansion of a BAL to @da@daCMPNE followed by the 
applicable argument Jist.e 


e Statement 76 shows the results of an invalid compare type. 


Example 2: Expansion of the Macro Instruction PRIME: 


The following example illustrates the expansion of the macro 
instruction PRIME. PRIME generates a table of prime numbers 
%LENGTH long, beginning with the prime numbers ZPRIME1. 


MACRO 1 
PRIME APRIME1,4LENGTH 2 
LCLA *AL1,2ZAL2,2A1L3 3 
AIF (‘ALENGTH' LT °1°)&ER2 4 
AIF (*APRIME1" LT °2°)&ER1 5. 
”AL1 SETA *PRIME1 6 
AAL2 SETA ZAL1/2 dt 
ELOOP 1 AIF (AAL2 EQ 1)&GETREST 8 
AIF (AALI/ZALZ*AL2 EQ ZAL1)&ER1 9 
AAL2 SETA AAL2~-1 10 
AGO &LOOP 1 11 
EGETREST ANOP 12 
DAC *2AL1 13 
AAL3 SETA AAL3+1 14 
AIF (ZAL3 LT ZLENGTH)&LOOP2 15 
MEXIT 16 
&LOCP2 ANOP 17 
“AL 1 SETA AAL1+1 18 
*ZAL2 SETA AAL1/2 19 
ELOOP3 AIF (AAL2 EQ 1)EGETREST 20 
AIF (AALI/ZAL2Z*ZAL2 EQ ZAL1) &LOOP2 21 
%ZAL2 SETA *AAL2-1 22 
AGO ELOOF3 23 
GER 1 ANOP 24 
MNOTE ‘APRIME1 NOT A PRIME NUMBER‘ | 25 
MEXIT 26 
&ER2 ANOP 27 
MNOTE * LENGTH LT 1° 28 
MEND 29 
PRIME 13,5 30 
DAC 13 
DAC 17 
DAC 19 
DAC 23 
DAC 29 


PRIME 55,20 31 
*MNOTE °55 NOT A PRIME NUMBER'® 
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SUMMARY: 


If 


the operand replacing the symbolic parameter ZPRIME1 is not a 


prime number or if} “LENGTH is less than 1, macro expansion is 
Suppressed and an error message is passed to the source stream. 


ANA 


LYSIS 
Statements 1 through 29 constitute the macro definition. 


Statements 30 and 31 show two possible expansions of the macro 
instruction. 


statement 30 requests a table of prime numbers, 5 address- 
length constants long, beginning with the number 13. Because 
13 is a prime number, the expansion of the macro instruction 
takes place. 


Statement 31 requests a table of prime numbers, 20 
address-length constants long, beginning with the number 55. 
Because 55 is not 4 prime number, the macro expansion is 
suppressed and the’errer message results. 
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APPENDIX D 


CAL MACRO/32 PROCESSOR ERROR MESSAGES 


ERRCR CODE MEANING 
1 STRING TOO LONG 
2 ILLEGAL CHARACTER 
3 UNEXPANDABLE MACRO 
4 OPCODE NOT ALLOWED 


TO BE GENERATED 


> INVALID OPCOLE 

6 ILLEGAL OPCOLCE 

7 UNDEFINED VARIABLE 
SYMBOL 
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EXPLANATION 


The length of a string 


literal in a macro 
definition exceeds 255 
characters. 


An illegal character was 
encountered in the input 
stream and was changed to 
a a 


A macro invocation was 
encountered which cannot be 
expanded because of errors 
in the definition. 


An operation code allowed 
only in a source statement 
was obtained through 
substitution of a value for 
a variable symbol. 


The length of an operation 


code exceeds eight 
characters or the operation 
code is missing or not 


followed by a blank. 


An operation code allowed 
only ina macro definition 
was encountered in open 
code. 


A variable symbol, not 
declared ina BGBLx, GBLx, 
or LCLx statement or in a 
macro prototype, was 
encountered ina SETx, AIF, 
or model statement. 


ERROR CODE MEANING 


8 UNDEFINED SEQUENCE 
SYMBOL | 

9 UNDEFINED KEYWORD 
PARAMETER 

| 

10 MULTIPLY DEFINED 
MACRO NAME 

11 MULTIPLY DEFINED 


SETx SYMBOL 


12 MULTIPLY DEFINED 
SEQUENCE SYMBOL 


13 - MULTIPLY DEFINED 
PARAMETER 

14 ILLEGAL, PARAMETER 
SEQUENCE 


15 ILLEGAL |OPCOLE 


EXPLANATION 
A sequence symbol was 
declared in the operand 


field of an AIF or AGO 
Statement, but does not 
occur in the name field of 
any statement in the macro 
definition. 


A keyword was encountered 
in a macro instruction 
operand that does not 
correspond to any keyword 
in the macro prototype. 


A macro definition of the 
same name was encountered 
previously, or a macro was 
invoked before it was 
defined. 


A SETx variable symbol was 
defined more than once in 
an LCLx, BGBLx, or GLBx 
statement, or it has the 
Same name aS a parameter or 
system variable. 


A sequence symbol of the 
same name occurs in the 
same name field of a 
previous statement. 


A symbol parameter in a 
Macro prototype occurs more 
than once or has the same 
Name as a system variable. 


A keyword parameter 
precedes a positional 
parameter in a macro 


prototype or instruction. 


A BGBLx, GBLx, or LCLx 
SEQUENCE statement does not 


precede all executable 
statements in a macro 
definition, or an ACTR 
statement does not 
immediately follow the 


declaration statements. 
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ERRCR CODE 


16 


17 


18 


19 


20 


21 


22 


23 


24 


25 
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MEANING 


ILLEGAL VARIABLE 
SYMBOL 


ILLEGAL SECUENCE 
SYMBOL 


ILLEGAL DECLARATION 


ILLEGAL MACRO 
NAME 


MISMATCHED SETx 
TYPE 


MISSING SETx 
SYMBOL 


MISSING SEQUENCE 


SYMBOL 


ILLEGAL NAME FIELD 


NON-BLANK NAME FIELD 


MISSING OPERAND 


EXPLANATION 


A variable symbol is longer 
than seven characters or 
has a first character that 
is not alphabetic. 


A sequence symbol is longer 
than seven characters or 
has a first character that 
is not alphabetic. 


The syntax of a BGBLx, 
GBLx, or LCLx statement is 


incorrect. Either an 
operand is not a variable 
symbol or a comma is 
missing. 


The length of a macro name 
exceeds eight characters or 
corresponds to a reserved 
opcode, or the syntax of 
the operand field of an 
MCALL statement is 
incorrect. 


The types of the SETx 
variable statements and the 
variable symbol in the name 
field of that operation do 
not match. 


The name field of a SETx 
Statement is blank or does 


not contain a variable 
symbol. 
A sequence symbol is 


missing in the name field 
of an ANOP statement or in 
the operand field of a AGO 
or AIF statement. 


The statement name field in 
a macro definition contains 
a token forbidden in that 
position. 

Self-explanatory. 


self-explanatory. 


ERROR CODE 


26 


27 


28 


29 


30 


31 


32 


33 


34 


35 


36 


37 


MEANING 


ILLEGAL ARITHMETIC 


EXPRESSION 


ILLEGAL BOCLEAN 
EXPRESSION 


ILLEGAL CHARACTER 
EXPRESSION 


EXPRESSION STACK 
OVERFLOW 


INVALID ATTRIBUTE 
FUNCTION 


ILLEGAL ATTRIBUTE 
FUNCTION 


t 


TYPE FUNCTION NOT 
ALONE 


ILLEGAL, SUBLIST 
NOTATION 


MISMATCHED 
PARENTHESES 


MISMATCHED QUOTES 


MISSING COMMA 


| 


ILLEGAL) QUCTE 


EXPLANATION 


The syntax of OP, an 
arithmetic expression, 
cannot be parsed. 


The syntax of a Boolean 
expression cannot be 
parsed. 


The syntax of a character 


expression cannot be 
parsed. 

An arithmetic, Boolean, 
binary, or character 


expression was encountered 
that exceeds 15 levels of 
parentheses with two 
operations pending at each 
level. 


The operand of an attribute 
function is not a symbolic 
parameter. 


A type attribute function 
occurs in an arithmetic 
expression. 


A type attribute function 
is not the only element in 
a character expression. 


The Syntax of a sublist 
notation is incorrect. 


The parentheses in a macro 
instruction, or prototype, 
or character expression do 
not balance. 


The quotes in a macro 
instruction or prototype, 
Or in a character 
expression or model 
statement do not balance. 


A comma is missing. 
An illegal quote was 
encountered in the name 


field or operation field of 
a model statement. 
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ERRCR CODE 


38 


39 


40 


4 


42 


43 


4 


45 


46 


47 


48 
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MEANING 


ILLEGAL SYMBOL 


UNRECOGNIZABLE 


SYMBOL 


BATCH IN ILLEGAL 


POSITION 


FND BEFORE MEND 


BEND BEFORE MEND 


ILLEGAL BEND 


ILLEGAL SUBSTRING 
EVALUATION 


ILLEGAL SUBLIST 
EVALUATION 


ARITHMETIC OVERFLOW 


ACTR OVERFLOW 


ATTEMPT TO DIVIDE 
BY ZERO 


EXPLANATION 


A model statement contains 
an illegal character not 
enclosed in quotes. 


An expression contains an 


illegal character. 


A batch pseudo-op was 
encountered that is not the 


first statement of the 
program. 

An end pseudo-op was 
encountered in a macro 
definition. 

A bend pseudo-op was 
encountered in a macro 
definition. 

A bend pseudo-op was 
encountered but no 
preceding batch pseudo-op 


occurred. 


In substring notation, the 
value of the second 
expression is less than the 


value of the first 
expression. 

An expression in sublist 
notation evaluates to a 
negative number. 

An arithmetic expression 
evaluates to a number 
outside the range +2, 147, 
483, 647. . 

The arithmetic expression 
in an ACTR statement 
evaluates to a number 


greater than 32,767. 


Self-explanatory. 


ERROR CODE 


49 


50 


51 


52 


53 


54 


55 


56 


57 


58 


59 


60 


MEANING 


ILLEGAL ARITHMETIC 


OPERATION 


ILLEGAL LOGICAL 
UNIT 


ILLEGAL LABEL 


ACTR RUNOUT 
DICTIONARY SPACE 
FULL 


UNRECOGNIZABLE 
LINE 


TOO MANY SYMECLS 


BUFFER OVERFLOW 
ILLEGAL SUBSCRIPT 
MISSING SUBSCRIPT 


ILLEGAL ARRAY 
EXPRESSION 


DIMENSION OF ARRAYS 
TOO LARGE, INCREASE 


MEMORY | 


EXPLANATION 


An operand of an arithmetic 


operation is a SETC 
variable statement or 
symbolic parameter whose 


value contains other than 
an optional sign followed 
by numerics. 


The operand of an MLIBS or 
NOLIB statement is not 
numeric or an attempt was 
Made to assign an LU that 
was previously assigned or 
not presente 


The label in the operand 
field of an MCOPY statement 
is blank or contains an 
illegal character. 


Loop counter runout. 
Insufficient memory space 
was allocated for the macro 
processor's dynamic tables. 
A line was encountered 
in the input that is 
neither blank nor a comment 
nor a continuation card, 
but has a missing operation 
code. 

A symbol table overflow. 


A macro statement is over 
256 bytese 


A subscript is not 
arithmetic. 


Self-explanatory. 


Self-explanatory. 


Increase memory. 
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ERROR CODE 


61 


62 


63 


64 


65 


66 


67 


68 


69 
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MEANING 


ILLFGAL TYPE FOR AIF 
OR AGO 


DIFFERENT TYPE 
DECLARATIONS FOR 
GLOBAL VARIABLE 


SUBSCRIPT OUT OF 
RANGE 


NONEXISTENT SEQUENCE 
SYMBOL FOR CCMPUTED 
AIF OR AGO; INVALID 


CODE FOR SYSTEM MACRO 


MORE THAN 16 MACRO 
LIBRARIES 


MORE THAN 16 NESTED 
MCOPY STATEMENTS 


ILLEGAL OPTION FOR 
MLIST OR MCEES 


MACRO COMMENT 


ASIS ERROR 


EXPLANATION 
The variable symbol 1s not 
a type character. 
A global variable name was 
declared twice with 


different types. 


Out of range subscript was 
detected. 


Self-explanatory. 


Self explanatory. 


Self explanatory. 


Self explanatory. 


A statement with _* in 
columns 1and 2 is outside 
the macro definition. 


The statement is not 
allowed in the range of 
ASIS. 


GLOSSARY 


batch global set variable (EGBLx) symbol 
The BGBLx symbol communicates values between macro 
definitions or between different usages for the same macro 
definitions in different programs. It must be declared as 
batch global each time it is used in a macro definition. 

conditional branch (AIF) instruction 
The AIF instruction alters the macro definition statement 
processing sequence. 

conditional instruction loor counter (ACTR) instruction 
The ACTR instruction assigns a count other than 32767 as the 
Maximum number of AIF and AGO branches executed within a 
macro definition. 

conditional instructions 
Conditional instructions are instructions that can vary a 
Macro instruction at each invocation. 

count attribute 
The count attribute is the number of all characters in a 
Macro instruction field. It includes all characters in the 
operand plus apostrophes; but, it does not include delimiting 
commaSse 

generated statements (expanded statements) 
Generated statements are the assembler statements the 
processor processeSe 

global SET variable (GBLx) symbol 
The GBLx symbol communicates values between macro definitions 
or between different usages for the same macro definition in 


a programe It must be declared as global each time it is 
used in a macro definition. 
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header record 


A header record is the first record in any macro library. It 
contains: the last date the library was modified, the 
library size, the medium type, and user comments. 


index records 


Index records are records used to locate macro definitions 
within a library. Each index record contains from 0 to 21 
entries. . 


inner macro instruction 


When the mnemonic operation code for a given macro definition 
appears as the operation field of a model statement in 
another macro definition, the model statement is an inner 
macro instruction. 


keyword 


A keyword is the portion of a symbolic parameter that does 
not include the percent sign. 


keyword macro instruction 


A keyword macro instruction is a specific type of macro 
instruction in which each operand must consist of a keyword 
immediately followed ty an equal sign (=), followed 
(optionally) by a value. 


local SET variable (LCLx) symbols 


The LCLx symbols communicate values within the same usage of 
a particular macro definition. It is only declared in the 
macro definition that it is used in and it is reset to its 
initial value each time that macro definition is invoked. 


Macro call (MCALL) instruction 


The MCALL instruction permits the cited macros to be called 
as they appear in the library rather than as they appear in 
the processor source stream. 


A macro definition is a series of user written statements in 
the macro language. The language enables the user to assign 
a mnemonic operation code to the definition. This mnemonic 
operation code causes the definition to be invoked. A macro 
definition minimally consists of: a name, operation, 
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operand, comments, continuation, and identification/sequence 
field used for writing macro instructions. 

macro definition header (MACRO) 
A macro definition header indicates the beginning of a macro 
definition. It must be the first statement. 

Macro definition trailer (MEND) 
A macro definition trailer indicates the end of a macro 
definition. It must be the last statement in the definition. 

macro definitions (MDEFS) instruction 
The MDEFS instruction controls which macro statements are 
sent to the CAL file. 

macro instruction 
A macro instruction is a single instruction that expands to 
a series of instructions. It invokes and processes a given 
Macro definition. The instruction can be positional, 
keyword, or mixed operand, corresponding to the three forms 
of macro prototype statements. 

Macro instruction prototyfre statement 
A macro instruction prototype statement specifies the 
mnemonic operation code and general format to be used when 
writing any macro instructions referring to this definition. 

Macro library 
A macro library is a 256-byte record file containing: a 
header record, index records, and macro definitions. 

macro libraries (MLIBS) instruction 
The MLIBS instruction deSignates the file descriptor or 
decimal LU numbers where the macro libraries, necessary ina 
given macro processor source stream, reside. 

Macro trace (MTRAC) instruction 
The MTRAC instruction, a diagnostic instruction, determines 


the effective conditional branches and the SET variable 
symbols values within the macro logic. 
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MCOPY statement 
The MCOPY statement enables source text to be copied from a 
specified LU or file descriptor at any point in a macro 
definition or programe 

MEXIT instruction 
The MEXIT instruction terminates the current macro definition 
expansion. 

mixed mode macro instructions 
Mixed mode macro instructions are a specific type of macro 
instruction in which all positional operands must be placed 
before any keyword operands. 

mnemonic operation code 
A mnemonic operation code is a user-assigned code that 
enables the macro definition to be invoked. 

model statements 
Model statements are statements from which the CAL Macro 
Frocessor expands the desired source statements. The four 
fields of a model statement are: Name, operation, operand, 
and comments. 

no libraries (NOLIB) instruction 
The NOLIB instruction suppresses searching all or some macro 
libraries previously designated by the MLIBS statement. 

no operation (ANOP) instruction 
The ANOP instruction is used when the sequence symbol in an 
AIF or AGO instruction must reference a statement already 
containing a symbol (cther than a sequence symbol) in the 
name field. 


no trace (NTRAC) instruction 


The NTRAC instruction causes the macro trace feature to be 
disabled. | 
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number attribute 
A number attribute is a value equal to the number of operands 
in an operand sublist. The number is equal to one plus the 
number of delimiting commas appearing within the sublist. 

outer macro instruction 
When the mnemonic operation code for a given macro definition 
appears aS the operaticn field of a model statement in 
another macro definition, the macro instruction referring to 
the containing definition is an outer macro definition. 

pause (MPAUS) statement 
The MPAUS statement permits the user to pause the macro 
PLOCeSSOL. 

positional macro instructions 
Positional macro instructions are a specific type of macro. 
instruction in which placement of the symbolic parameters in 


the operand field of the macro prototype statement determines 
placement of operands. 


The MNOTE instruction generates a macro message. 


sequence symbols 
Sequence symbols are symbols that can appear in a statement 
name field to vary the statement processing sequence. 

SET arithmetic variable (SETA) instruction 
The SETA instruction assigns an arithmetic value to a SETA 
symbol or array element. 

SET binary variable (SETB) instruction 
The SETB instruction assigns the value true (binary 1) or 
false (binary 0) to a SETB variable symbol. 

SET character variable (SETC) statement 


The SETC statement assigns a character value to aéSETC 
variable symbol. 
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SET variable statement (SETx) instruction 


The SETx instruction alters the variable symbols value that 
the BGBLx, GBLx, or LCLx declaration statements declared as. 
SET variable symbols. 


sublist 


A sublist is one or mcre operands separated by commas and 
enclosed in paired parentheses. The entire sublist, 
including the parentheses, is one macro instruction operand. 


substring notation 


Substring notation allows a part of a character value to be 
assigned toa SETC variable symbol indicating in the operand 
field of a SETx instruction the character value or an 
expression representing the character value to be assigned to 
the SETC variable symbol. 


symbolic parameters 


A symbolic parameter is a variable consisting of a percent 
sign (%) followed ky from one to seven letters or numbers, 
the first of which! must be a character. These parameters, 
used in the macro definition, represent the name field and 
operands of the correspcnding macro instruction. 


type attributes 
Type attributes are attributes of a macro instruction operand 
that can be used whenever a character expression could be 
used; but the type attribute must occur alone (that is, not 
concatenated with anything) and it must not be enclosed in 
quotes. 

unconditional branch (AGO) instruction 
The AGO instruction alters the sequence in which’ macro 
definition statements are processed. 

“%SYSDATE macro variable symbol 
The %SYSDATE symbol is an eight character string system 


variable whose value represents the date that the macro 
processor was invoked. 
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*ASYSINDX macro system variable symbol 


The ~2SYSINDX is a system variable whose values can hbe 
concatenated with other characters to create unique names for 
statements generated from the same model statement. 


*ZSYSLIST macro system variable symbol 


The &ZSYSLIST is a system variable that provides an 
alternative to symbolic parameters for referencing to 
positional macro instruction operands. Both A&SYSLIST and 
symbolic parameters can be used in the same positional macro 
definition. 


”ZSYSMAC macro system variable symbol 
”ZASYSMAC is a system variable that differs from the system 


variable &SYSINDX because the value changes due to inner 
Macrc calls. 


ASYSTIME macro system variable symbol 


A”ASYSTIME is an eight character string system variable whose 
value is that time of day that the macro processor was 
invoked. 
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Macro definition, preparation 
macro definition contents 
Macro definitions 
macro instructions 
model statements 
special symbols 

Macro instruction operands 
continuation of macro in- 

structions 
omitted operands 
sublists 

Macro library 
header record 
index records 
Macro definitions 

Macro library utility program 
command format , 
macro library 
macro library utility com- 

mands 
operation of a macro li- 
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operation with a macro li+ 
brary On magnetic tape 

Model statements, 

comments field 
concatention rules 

name field 

operand field 

operation field 

using symbolic parameters 
in model statements 
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